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Visual Development Environment For 


Powerful Open 


WATCOM VX-RExx 





esign Applicaticns Inte 
Visually Create rich graphical 


is an easy to use visual development 
environment for creating applications that leverage the Env 
capabilities of OS/2 2.x and exploit the Presentation Manager 
graphical user interface. VX*REXX combines a project 
management facility, visual designer and an interactive source- 
level debugger to deliver a very approachable and highly 
productive visual development environment. 


grated Development 
Envir onmen it Build, test and 


ironment Enjoy the 
simplicity of event-driven 
programming together with the 
global editing capabilities 
essential for professional project 
management. WATCOM 

V X*REXxX is open and extensible 
through IBM’s object oriented 
System Object Model (SOM) 
technology. You can access all 
standard REXx API’s including 


applications quickly and easily using 
the visual design environment. With 
the visual designer, you can 
graphically create Presentation 
Manager interface objects, quickly 
customize their properties, and 
easily attach REXX procedures using 
powertul drag-and-drop 
programming techniques. 


debug your application without 
leaving the development 
environment. Then package your 
application as an EXE file or PM 
macro for royalty-free redistribution. 
The power of the integrated 
development environment and 
debugger can also be used with your 
existing REXX applications. 


DB2?/2, because VX*REXX Is 
based on the OS/2 2.x standard 
system REXX. 























Highlights 

> Easy to use visual development environment 

> Create and modify objects dynamically at 
both edit and run time 

> Powerful project management facility 

> Advanced interactive source-level debugger 

> Package your applications as EXE files or 
PM macros 

> Access to standard Rexx API’s including 

DB2/2 


> System Object Model (SOM) based object 
manager 






> Drag-and-drop programming cast 
> Support for multi-threaded applications Weary 
H : Mil ‘3 Do i 
> Include 0S/2 style help and hints in your irs 
\ wu 


applications 

> Supports SAA CUA’91 objects 

> Integrated console window support for 
existing RExx programs 

> Royalty-free run-time 

> Multiple modeless window support 


> Create PM macros for applications 
Supporting RExx as a macro language 





interactive Debugging 
If an error occurs at run-time, 
VX*REXxx will display a traceback 
pinpointing the source line where 
the error occurred. A simple click 
of the mouse will return you to the 
source edit window to correct the 
error. The built-in interactive 
source-level debugger lets you set 
breakpoints, step through code 
and watch variables to track down 
complex problems. 















Build Professional 


Applications 
WATCOM VX°RExx allows 
you to leverage key OS/2 features 
to create professional applications. 
Build applications that dynamically 
create and modify CUA’91 screen 
objects at both edit and run-time, 
and include OS/2 style help and hints. 


Create Multi-Threaded 
Applications Every Vx-Rexx 


application contains multiple threads. 
One thread remains responsive to user 
input while others continue processing. 
In addition, VX*REXx provides the simp 
ability for advanced applications to easily 

use additional threads. 
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Suggested Retail: $199* 


Call Toll Free 
1-800-265-4555 





WATCOM VX-Rexx 


The integrated visual 
solution builder for OS/2 2.x. 








WATCOM International 
415 Phillip Street, Waterloo, Ontario, Canada, N2L 3X2 
Phone: (519) 886-3700 Fax: (519) 747-4971 


*Prices and specification are subject to change without notice. Price does not include freight and taxes where applicable. Prices 
quoted in US dollars. WATCOM, the Lightning Device, and VX*Rexx are trademarks of WATCOM International Corporation. Other 
trademarks are the properties of their respective owners. © Copyright 1993 WATCOM International Corporation. 
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G6 We were told it was impossib 


to develop a client Server application 
without extensive retraining 
Then we talked to Micro Focus: 


Larry Lowder, Systems Architect, Questar Service Corporation. 


Mountain Fuel Supply? a division of Questar? is a utility company 
supplying natural gas to 750,000 customers across Utah, Wyoming, Idaho 
and Colorado. The company’s success is largely driven by its implicit belief 
that the customer is number one. 

Yet, IT also plays its part in that success: client/server architectures and 
graphical user interfaces (GUIs) have helped Mountain Fuel Supply move 
applications and information closer to the customers and the employees. All 
of which has resulted in an augmented level of service being offered to 
customers. 

When Larry Lowder, one of Questar’s Systems Architects, set out to 
build the client/server architecture for Mountain Fuel Supply, he needed 
solutions, not skepticism. For the first project, a cashiering system, he 
needed to link workstations with OS/2® to the DB2® database on the host, 
running CICS* 


“We were faced with having to spend up to two years retraining our 





COBOL programmers in C and API calls. Then we discovered Micro Focus 
Dialog System™ It allowed us to build the client functionality we required, 
and re-engineer the existing mainframe application as a server.” 

“Within a week, mainframe programmers were producing GUI screens 
for COBOL. Within 90 days we had delivered the system. Now we're not 
only coming in under budget, but also way ahead of schedule.” 

As Mountain Fuel Supply discovered, the Micro Focus solution lets 
you make a productive transition to client/server without sacrificing any of 
the resources you've worked so hard to build. 

When the world’s leading corporations demand “A Better Way of 
Programming,” they turn to Micro Focus. For a brochure on putting the 


Micro Focus Client/Server Solution to work for you, call 800-872-6265. 


Micro Focus Inc. 2465 East Bayshore Road, Palo Alto, CA 94303. Tel. (415) 856 4161. 


Micro Focus is a registered trademark and Dialog System and “A Better Way of Programming” are trademarks of Micro Focus, Inc. All other trademarks are property of their respective companies 
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by One Up Corporation 
SourceLink, the ultimate 32-Bit programming 
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he SOMObjects Toolkit is a product 

designed for programmers involved in 

object-oriented programming. The Toolk- 
it includes both the SOM Kernel and the SOM 
Frameworks. The SOM Kernel provides a mecha- 
nism for writing language-independent object-ori- 
ented classes. By language-independent, we mean 
that the class consumer can use a different lan- 
guage than that used by the class implementor, as 
long as both consumer and implementor lan- 
guages supports SOM bindings. The SOM Frame- 
works greatly decrease the programming effort 
required to give those classes basic functionalities 
such as persistence and object distribution. 

In this article, we'll introduce you to the use of 
the SOM Kernel and SOM compiler. These two 
components provide the basic functionality need- 
ed to create classes. We'll develop a complete 
example and give you all the information you'll 
need to compile and run each example. We 
assume only that you have installed the toolkit 
according to the installation directions. This will 
allow you to use the examples as the basis for your 
own programming efforts. 


INTRODUCTION TO THE 

SOMOBJECTS TOOLKIT 

The process of creating a SOM class is summa- 
rized in Figure 1. The programmer defines a class 
in a language known as the Interface Definition 
Language, or IDL. This definition is placed in a file 
typically named with the extension idl. The SOM 
compiler is run against this IDL file and three files 





release of the product, often described simply as “SOM,” includes not only major upgrades on the SOM kernel 
itself but also includes several important frameworks that provide new development opportunities for the 
designer and implementor of SOM objects. BY ROGER SESSIONS, NURCAN COSKUN, and CHARLES ERICKSON 


SOMObjects Developer Toolkit: 
An Overview 


are generated. The first is a header file used for 
class implementation code, named with the exten- 
sion ih. The second, a header file used by clients, is 
named with the extension h. The third is a method 
template file containing C code skeletons for each 
method described in the class definition, named 
with the extension c. These skeletons are filled in 
by the programmer. 

Programmers who used the first version of SOM 
will notice right away that the class definition lan- 
guage has changed. Classes used to be defined with 
a language known as OIDL, or Object Interface Def- 
inition Language. Although OIDL is still supported, 
we are encouraging people to port their code to the 
IDL syntax for several reasons. Perhaps the most 
important is that the IDL syntax used to define 
classes and the associated C bindings has been 
accepted as an industry standard. The standard has 
been worked out through the Object Management 
Group (OMG) and their CORBA specification. 
Another reason for moving to IDL is that it allows 
use of new SOM Frameworks including Distributed 
SOM or DSOM. 

As changes are made to the IDL file, the SOM 
compiler must be rerun. The .ih and .h files are 
regenerated and the .c file modified to add new 
skeletons for any newly defined methods. Exist- 
ing method code is left untouched. 


BASIC PROGRAMMING EXAMPLE 

Let's start by looking at the definition, implemen- 
tation, and use of a simple SOM class: an appoint- 
ment. An object of the appointment class knows 
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about a particular appointment during the day. 
Appointments are characterized by a date, start- 
ing time, ending time, and subject. The subject is a 
description of the appointment’s purpose. 

A high-level description of this class in class 
definition pseudocode is shown in Figure 2. 
Appointment is derived from SOMObject, the default 
root class for all class derivations. We have indi- 
cated the direction of all parameters. The keyword 
in is used to indicate a parameter that is not updat- 
ed. All of our parameters are in. 

There are a series of relationships between cer- 
tain instance data and pairs of methods. For exam- 
ple, there are the instance data year and the two 
methods set_year() and get_year(). It is quite com- 
mon to have a particular piece of instance data 
associated with a set method, which sets the value, 
and a get method, which returns the value of the 
instance data. 

There is a shortcut to declaring an instance 
data, a set and a get method—declaring an 
attribute. If we see an attribute year, we can inter- 
pret this as declaring a data element year, and a set 
and a get method. By using attributes, we can sim- 
plify Figure 2. The new high-level description of 
appointment using attributes is shown in Figure 3. 

Appointment includes a method named buffer- 
ize(). We will follow a rule that says object imple- 
mentation and I/O should be kept separate. 
Another way of saying this is that objects should 
be separated from code that prints them out or 
reads them in. We use the method bufferize() as a 
convenient way to request an Appointment object to 
return a formatted string information about its 
contents. The separation of object implementation 
from I/O will greatly simplify the use of several 
frameworks of the SOMObjects Toolkit. 

We also want Appointment to override certain 
methods inherited from SOMObject. The overriden 
methods are somInit(), the method invoked on an 
object when that object is first created, and 
somninit(), the method invoked on an object when 
that object is destroyed. Updating Figure 3 to 
show overridden methods gives Figure 4. 

Notice that SOM has predeclared certain types. 
These types can be used in the declaration of 
attributes, return values for methods, and parame- 
ters of methods. The valid types are shown in Fig- 
ure 5. In this article, we use only short (which is 
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class.idl Class Definition File 


class.c Template file for class implementation. 
class.h | Header file for client code. 
class.ih | Header file for class.c 


Method body filled in by class implementor 
C Compiler 


Loader 


Figure 1. Summary of the SOM process 





Figure 2. High-level description of Appointment class 
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equivalent to the C type short int), 
string (equivalent to the C type char#), 
and sequence (equivalent to a specific 
structure in C). 

The IDL file that defines the Appoint- 
ment class, appt.idl, is shown in Figure 
6. Line numbers are given for ease of 
reference. It should be relatively easy 
to relate this back to the high level 
description shown in Figure 4. 

Let’s go through the IDL file shown 
in Figure 6 line by line. 

Lines 01, 02, and 52 ensure that this 
file is compiled only once. This is simi- 
lar to the technique used in C++ to 
ensure that class definitions in that lan- 
guage are compiled only once (see Ses- 
sions, Class Construction in C and C++). 

Line 04 includes the IDL definition 
for the base class of this class. 

Line 06 declares Appointment to be an 
interface (or a class, for our purposes) 
and notes that the class is derived from 
SOMOb ject. Notice that the interface dec- 
laration encompasses lines 07-50, inclu- 
sive, as indicated by the brackets. 

Lines 12, 15, 18, 21, 24, 27, and 30 
declare the attributes for the class. Line 
08 declares the only method of the 
class. 

The implementation section of the 
class declaration begins at line 32 and 
ends at line 49 (again as indicated by 
brackets). This section contains infor- 
mation not considered part of the inter- 
face per se, but still necessary to the 
class declaration. Pragmatically, the 
implementation section contains any 
information that is an extension of the 
OMG CORBA standard. Notice that the 
implementation section is within the 
interface section. 

Within the implementation section, 
we see a dllname statement at line 34. 
The purpose of this is to tell SOM the 
name of the dll into which the object 
code for this class will be built. This 
information is used by SOM to locate 
and dynamically load class libraries. 

Also within the implementation sec- 
tion, we see a releaseorder section from 
lines 35-38. This section is designed to 
ensure that base classes can be modi- 
fied without forcing derived classes to 
be recompiled. We will not explain 


class: Appointment 
derived from: SOMOb ject 
attributes: short year 
short month 
short day 


short startingTime 


short endingTime 
string subject 


methods: string bufferize(in string buffer) 


Figure 3. High-level description of Appointment class using attribute 


Appointment 
SOMOb ject 
short year 
short month 
short day 


class: 
derived from: 
attributes: 


short startingTime 


short endingTime 

string subject 
methods: 

overriden methods: somInit 
somUninit 


string bufferize(in string buffer) 


Figure 4. High-level description of Appointment class using attributes and showing 


overridden methods 


Basic Types 


struct 
union 
enum 


short 

long 

unsigned short 
unsigned long 
float 

double 

char 

octet 

boolean 

any 


Figure 5. Valid IDL types 


how this works technically, but the 
rules for implementing this section are: 
Whenever a method is added to the 
class, it is added to the release order. 
Methods should never be removed 
from the release order (even when 


Constructed Types 


Template Types 


sequence 


string 


removed from the class) and methods 
should never be moved within the 
release order (even when moved with- 
in the class). Notice that these rules 
apply to methods implied by attributes, 
(such as _get_year()) as well as explicit 
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Figure 6. IDL definition for Appointment, appt.id1 
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Gary Slattery, Software Developer, Computer Associates 


“The best platform for 
DOS and Windows.” 


“I develop software applications for a living 
and I think OS/2° is a great way to do 
business.” A 32-bit, virtual memory operat- 
ing system, OS/2 is the ideal platform for 
developing your DOS, OS/2, Windows™ and 
even host-based applications. 

With OS/2 you can boost the power of 
your favorite DOS and Windows tools, 


IBM and OS/2 are registered trademarks and Workplace Shell, C++, CommonvView, 

C Set/2 and OS/2 Crash Protection are trademarks of International Business Machines 
Corporation. All other products are trademarks or registered trademarks of their respective 
companies. ©1993 IBM Corp 


plus take advantage of over 290 available 
OS/2 development tools and utilities. 


“It’s a productivity thing. 

“lL use CA Realizer to prototype new 
graphical interfaces. | write code using 
CA C++™ and CommonView™ (integrated 
with IBM’s C Set/2™ compiler) 
while I compile in the 
background. And when 
designing reports or 
planning schedules, 
I use CA-RET” 

OS/2’s pre-emptive 
multithreaded multitasking dynami- 
cally manages CPU time so you can run 
DOS, Windows and OS/2 apps 
concurrently in different sessions 
with maximum efficiency. That 
means you can edit in one win- 
dow, compile in another, link in a 
third and test in a fourth. With OS/2 Crash 
Protection,” if one application goes down 
due to a bug, the rest youre working on 
wont. “There's no limit to what you can do 
with this system.... It's definitely made me 
more productive.” 
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The Development Platform of Choice 


* Enhanced development platform for DOS, Windows and 
OS/2 apps. 

* OS/2 Crash Protection for superior reliability. 

* Pre-emptive multitasking for increased productivity. 

* Virtual memory provides up to 512MB per session. 

* Flat memory model eliminates wrestling with segments. 


* Multiple virtual DOS machines for concurrent app 
testing. 
* Object-oriented Workplace Shell is easy and intuitive. 





The object-oriented 
user interface—the Workplace 
Shell” (WPS)—gives you easy control with 
direct manipulation of visual objects on 
your computer screen. And should you need 
assistance with anything, IBM’s Worldwide 
Developer Assistance Program is always there 


to help. 
| 
“i developers dream. 





Use OS/2 to increase productivity of DOS, Windows and 
OS/2 application development. 





With OS/2’s 32-bit architecture, you can 
push your 386 and 486 hardware to the limit, 
and develop spectacular multimedia 1222 
and enterprise-wide Client-server o'tothica tscolerce 
applications. OS/2 lets you create . 
the widest range of applications, 
for a variety of platforms, for 
almost any size computer. Here’s 
your chance to develop truly 
revolutionary 32-bit applications. With 
OS/2, now there’ nothing stopping you. 

‘To learn more, call 1 407 982-6408 
now, and get a free white paper on why OS/2 
is the ideal platform for your 
development efforts. 





os 2, Version 2.0 
IBM Corporation 
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methods (such as bufferize()). 

The overrides are declared as shown 
in lines 41 and 42. Notice that parame- 
ters of overridden methods are not 
given here; they can be inferred from 
the IDL file describing the base class. 

Attributes can be modified, as 
shown in line 45. The only attribute 
modifier we use is noset. The keyword 
noset tells the SOM compiler that we 
don’t want a set method automatically 
generated for this attribute. Instead, we 
want to write our own. We'd do this in 
a situation where the set method that 
would have been generated wouldn't 
be adequate for our purpose. The 
default set methods generated for string 
attributes are almost always inappro- 
priate and must be written by hand. 

We can see why it is best to hand 
code the set methods for string attribut- 
es if we look at what would have been 
generated for the set method had we 
not used noset. The default set method 
is shown in Figure 7. 

The default set in Figure 7 is rarely 
appropriate for any attribute that is 
essentially a pointer to something 
because it results in memory leakage. 
A better algorithm for a set involving a 
pointer looks like: 

* See if data member is already point- 
ing to something 

* If so, free what it is pointing at 

e Allocate memory for the new value 

* Copy the parameter to the newly 
allocated memory 

* Set the data member to the newly 
allocated memory 

By using the noset modifier in line 45 
of Figure 6, we reserve for ourselves 
the right to write our own set for the 
attribute sub ject. 

Having completed the definition of 
Appointment, we are ready to use the 
SOM compiler to generate a file con- 
taining method skeletons. The com- 
mand to accomplish this is: 


sc -sc appt 


where appt is the root name of the file 
containing the definition of Appointment, 
and the .idl extension is assumed. 

This command produces the .c file 


SOM_Scope void SOMLINK _set_subject(Appointment *somSelf, Environment *ev, 


string subject) 
{ 


AppointmentData *somThis = AppointmentGetData(somSelf) ; 
AppointmentMethodDebug(" Appointment" ,"_set_sub ject"); 


somThis->subject = subject; 
} 


Figure 7. Default set method for attribute subject 


#define Appointment_Class_Source 
#include <appt.ih> 


SOM_Scope string SOMLINK bufferize(Appointment somSelf, Environment 


{ 


*ev) 


AppointmentData *somThis = AppointmentGetData(somSelf) ; 
AppointmentMethodDebug("Appointment" ,"bufferize") ; 


return; 


} 


SOM_Scope void SOMLINK _set_subject(Appointment somSelf, Environment *ev, 


{ 


string subject) 


AppointmentData *somThis = AppointmentGetData(somSelf) ; 
AppointmentMethodDebug(" Appointment" ,"_set_sub ject"); 


} 


SOM_Scope void SOMLINK somInit(Appointment somSelf) 


{ 


AppointmentData *somThis = AppointmentGetData(somSelf) ; 
AppointmentMethodDebug("Appointment","somInit") ; 
Appointment_parent_SOMOb ject_somInit(somSelf) ; 


} 

SOM_Scope void SOMLINK somUninit(Appointment somSelf) 
AppointmentData *somThis = AppointmentGetData(somSelf) ; 
AppointmentMethodDebug("Appointment" , "somUninit") ; 

. Appointment_parent_SOMOb ject_somUninit(somSelf) ; 


Figure 8. SOM Compiler generated .c file from appt.id1 


shown in Figure 8. 

Our job is to take the skeleton file in 
Figure 8 and fill in the body of the 
methods. Notice that the default set 
and get methods do not appear in this 
file, although those identified by noset 


OS/2 


do appear. (The default set and get 
methods can be found in the SOM com- 
piler generated appt.ih file.) The filled- 
in skeleton file is shown in Figure 9, 
again with line numbers added to facil- 
itate discussion. 


DEVELOPER 


C Set++- 


Get set for incredible 32-bit power. Get set for 
mission critical reliability. Get set for a range 
of advanced features. Get C Set+-+£" from IBM 
Programming Systems. C Set++ is the 


most complete object-oriented applica- 

tion development package you can buy 

for OS/2° ! : eC 
C Set++ lets you create the most QO 


advanced, high-performance applica- 
tions imaginable. Its 32-bit C/C++ compiler lets 
you unleash all the power of OS/2, giving you 
industrial-strength code for your mission critical 
applications. It has an extraordinary code opti- 
mizer with a full set of options—even 
a switch to optimize for the new Pentium” | 
processor. Plus there’s a full set of ~ 
class libraries, including application Cc 


oP ey 
I I 1 I ~ SION. Set your eyes on this: C Set++ gives the Workplace Shell™ 


quite a workout. 











frameworks for PM, container classes and classes With C Set++, it’s easier than ever to 
for multitasking, streams and more. set your sights on success. ‘To order or to 

There's a whole set of other helpful features, find out more about OS/2 2.1 or C Set++. 
like an interactive source level debugger. The call 1 800 3-IBM-OS2. In Canada, call 
unique Execution Trace Analyzer traces the exe- 1 800 465-7999, ext. 460. 


cution of a program, then graphically displays dia- 
grams of the analysis. You also get ra viagae ys 
a language-independent tool that lets you 

customize your own environinent. It’s sheets 


able and flexible— you can 
use any 16 and 32-bit DOS, 
Windows" and OS/2 tools. 


IBM and OS/2 are registered radémarks and G Set+ +, WofKplace Shell, Workframe/2 and 
“Operate at a higher level” are trademarks of Internationa! Business Machines Corporation 
Pentium is a trademark of Intel Corporation. Windows is a trademark of Microsoft Corp 
©1993 IBM Corp 
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Let’s go through some of the more 
interesting lines in the filled-in skele- 
ton in Figure 9. First we see some 
bookkeeping lines (lines 1-2). These are 
added automatically by the SOM com- 
piler, and we will not discuss their pur- 
pose here. Similarly, the keywords 
SOM_Scope and SOMLINK are seen within the 
method declarations. They are typical- 
ly equated to static and the null string 
respectively. Therefore the line: 


SOM_Scope string SOMLINK bufferize( 


can be thought of as being equivalent 
to: 


static string bufferize( 


We will not go into the reason for 
SOM_Scope and SOMLINK. 

The SOM compiler has automatical- 
ly supplied the correct parameters for 
each method, and that in addition to 
the parameters (if any) specified by the 
developer, SOM has supplied two 
implied parameters to every method 
(see, for example, line 5.) The first 
implied parameter is the receiving 
object, or what some authors describe 
as the target object. If you are not 
familiar with the concept of a target or 
receiving object, refer to Class Construc- 
tion in C and C+ (see the Bibliography). 
The second implied parameter is the 
Environment variable. Its primary pur- 
pose is to relay error conditions, a topic 
we will cover in a later article. 

Each method starts with some more 
bookkeeping lines such as 18 and 19, 
which we will not discuss here. If you 
need to declare local variables, they 
must precede the SOM supplied debug 
line. (For example, if the method 
somlnit() needed to declare local vari- 
ables, they would go before line 34.) 

When a method needs to refer to a 
data element, even when the data ele- 
ment is implied by an attribute, we 
refer to it using an underscore, as in 
line 23: 


_subject = NULL; 


01 #define Appointment_Class_Source 

02 #include <appt.ih> 

03 #define BUF_SIZE 512 

04 

05 SOM_Scope string SOMLINK bufferize(Appointment somSelf, Environment *ev) 
06 { 

07 AppointmentData *somThis = AppointmentGetData(somSelf) ; 

08 AppointmentMethodDebug("Appointment","bufferize") ; 

09 


10 = sprintf(_bp, "(/id) Date: Zd/4d/fd Start: id End: %d\nSubject =: %s\n", 
11 .apptId, _month, _day, _year, _start, _end, _subject); 

12 return(_bp); 

13 } 

14 


15 SOM_Scope void SOMLINK _set_subject( 

16 Appointment somSelf, Environment *ev, string subject) 
17 { 

18  AppointmentData *somThis = AppointmentGetData(somSelf) ; 
19 AppointmentMethodDebug("Appointment" ,"_set_sub ject"); 


21 if (_subject != NULL) { 
SOMFree(_sub ject) ; 
_subject = NULL; 
a>} 
25 if(subject == NULL) return; 
26 Subject = SOMMalloc(strlen(subject)+1) ; 
27 strcpy(_subject, subject); 
28 } 
29 
30 SOM_Scope void SOMLINK somInit( 
31 Appointment somSelf ) 
32 { 
33 AppointmentData *somThis = AppointmentGetData(sonSelf); 
34 —s AppointmentMethodDebug("Appointment","somInit") ; 


35 
36 Appointment_parent_SOMOb ject_somInit(somSelf) ; 
37 _year = 0; 
38 _month = 0; 
39 day = 0; 
_Start = 0; 
41 end = 0; 


42 _subject = NULL; 

43 _apptId = 0; 

44 _bp = SOMMalloc(BUF_SIZE) ; 

45 } 

46 

47 SOM_Scope void SOMLINK somUninit( 

48 Appointment somSelf) 

49 { 

50 AppointmentData *somThis = AppointmentGetData(somSelf) ; 
51 AppointmentMethodDebug ("Appointment ,"somUninit") ; 


Figure 9. Filled in skeleton file for Appointment (continued on page 16) 
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here 


This is the program, and the platform, BASIC was 
built for. Together, CA-REALIZER?® 2.0 and OS/2* 2.1 
go above and beyond BASIC. 

With CA-REALIZER, you get a visual program- 


& | 
ming tool that lets 
you develop visual =, BAS CC" je a 
applications with 
maximum impact. | 








It’s a structured superset of BASIC, extended to access brie Sanne | < : : 
na hg omgres ; [ools™ In short, its a developer's dreamkit. 
objects and resources of both Windows™ and OS/2. CACREAEIZER eliminates the netd faremmnber 
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You also get fully integrated Pr ogrammable Appli ator some SDKs. A totally new and improved visual FormDev 


lets you edit multiple forms simultaneously, as well as 
adding items like scroll bars, spreadsheets, charts, 
animation and OLE objects. You can even import or 
export 1-2-3, Excel and Xbase files. 

With its pre-emptive multitasking, OS/2 makes 
CA-REALIZER a faster BASIC to work with, allowing 
you to move on while the system completes the previous 
job. And the applications you create can be compiled into 
stand-alone OS/2 programs you can distribute royalty- 
free with the run-time module that’s included. Theres 
even an award-win ning report writer at no extra charge. 

Clearly, when it comes to BASIC, CA-REALIZER 
is anything but.'lo order or find out more about 
OS/2 2.1 or CA-REALIZER, call 1800 3-IBM-OS2* 

In Canada, call 1 800 465-7999. 


Operate at a higher level. 


better. 
















Realize the full power of your PC with OS/2, and youll 
never go back to BASICs. 
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The underscore is used to indicate a 
data element of the target object of this 
method invocation. 

Memory allocation and deallocation 
uses the SOM-supplied functions SOM- 
Malloc() and SOMFree() (as seen in lines 
26 and 59) instead of their standard C 
counterparts. 

When you want to invoke the 
method defined for your base class, use 
the syntax MyClassName_parent_BaseClass- 
Name_MethodName (parameters). A typical 
example of this is seen in line 36, where 
we have the somInit() method invoking 
its base classes somInit(). somInit() is the 
method automatically invoked on an 
object when that object is first created. 
This is where one typically places any 
initialization code. 

The implementation file includes 
code for set_subject(), the set method 
for the attribute subject that we wanted 
to write ourselves via the noset modifi- 
er. The code for this method follows the 
algorithm given earlier for set methods 
involving pointer attributes. 

The initialization method, somInit(), 
sets up a newly instantiated Appointment 
object. Typically the first thing an 
implementation of somInit() does is to 
request the base class initialization, 
thus the invocation in line 36. The 
deinitialization method, somUninit(), 
performs the reverse operation. 

A very simple client program that 
uses this class is shown in Figure 10. 
Notice that the client code has no 
knowledge of the Appointment class other 
that the interface section of the IDL. 

If we look at the client program 
shown in Figure 10, the first thing we 
see is the use of the SOM compiler gen- 
erated appt.h file. This file contains all 
of the information needed for a client 
to use a SOM class. 

The client declares an object of class 
Appointment and instantiates the object, 
as shown in line 5. The client invokes 
methods using an underscore preced- 
ing method names (as shown in line 17) 
and a double underscore preceding set 
or get methods for attributes (as shown 
in lines 8-14). 

All methods take as their first para- 


_year = 0; 

_month = 0; 

day = 0; 

_start = 0; 

end = 0; 

if (_subject != NULL) { 
SOMFree(_sub ject) ; 
subject = NULL; 

} 

62 SOMFree(_bp) ; 


§=$=SSeErtaagastars 


63. —- Appointment_parent_SOMOb ject_somUninit(somSelf) ; 


64 } 


Figure 9. Filled in skeleton file for Appointment (continued from page 14) 


01 #include <appt.h> 
02 

03 main () 

04 { 


05 Appointment appt = AppointmentNew(); 
06 Environment *ev = SOM_CreateLocalEnvironment(); 


07 

08 __set_month(appt, ev, 12); 
09 __set_day(appt, ev, 05); 
10 __set_year(appt, ev, 1993); 
11 __set_start(appt, ev, 900); 
12  __set_end(appt, ev, 1100); 


13 __set_subject(appt, ev, "Product Planning"); 


14 __set_apptId(appt, ev, 1); 
15 


16 somPrintf("%s\n", _bufferize(appt, ev)); 


17 __somFree(appt); 


18  SOM_DestroyLocalEnvironment(ev) ; 


19 } 


Figure 10. Sample client program For Appointment class 


we eee eee eee ae aa 
(1) Date: 12/5/1993 Start: 900 End: 1100 


Sub ject : Product Planning 


Figure 11. Output from the sample client program 


meter the receiving object. Most meth- 
ods take as their second parameter a 
pointer to an environment. (This will be 
discussed in a later article on error han- 
dling. For now, declare and allocate an 
environment using the syntax shown in 


line 6 and free the associated memory 
using the syntax shown in line 18.) 
Notice that not all methods take an 
environment pointer. Assuming you 
use standard IDL processing, any 
methods you declare will take an envi- 
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Developers: on your marks, get set-—GUI! 
With VX-RExx?" WATCOM™’s 
visual development environment 
for OS/2° REXX, you're on the fast 
track to creating applications that 
exploit the graphical user interface 
capabilities of OS/2 and the Workplace Shell? 
VX*REXX is an easy to use, powerful and fully 
integrated environment that combines a project 
management facility, visual designer and 
an interactive source-level debugger to 
deliver a very approachable and highly 
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productive visual development environ- 
ment. With the visual designer, you can graphically 
create CUA 9] objects, quickly customize their 


‘= f 1 : OU With the visual development environment of VX*REXYX, 





it’s all systems GUI. 


properties, and easily attach REXX proce- 

dures to the objects. f | =n 
Since it’s based on IBM System Object 

Model (SOM) technology, the VX*REXX J 


environment is wide open. You can access 
all standard REXX API's including DB2/2. VX*REXX 


also lets you package applications as EXE files or PM 





system. So when it comes to developing 
OS/2 applications, VX*REXX is the way 
to GUL. To order or to find out more about OS/2 2.1 
or VX*REXX, call 1 800 3-IBM-OS2. In Canada, 
call 1 800 465-7999. 


macros. There’s support for multithreaded applica- 

tions. You can even include OS/2 style help and hints 

in your applications. i: 
To keep GUI-ing, WATCOM customer support Operate ata higher level. 

delivers timely response by phone, fax, e-mail, | 

CompuServe, or the WATCOM bulletin board 


——S_ IES ee 

———- ti 
IBM and OS/2 are registered trademarks and “Operate al a higher level” and Workplace Shell are trademarks of a 
International Business Machines Corporation. WATCOM and VX*Rexx are trademarks of WATCOM International — — == 
Corporation. CompuServe is a trademark of CompuServe Incorporated. © 1993 IBM Corp = oe 





18 


ronment pointer. The only methods 
you are likely to run into that do not 
take an environment pointer are those 
declared in SOMOb ject and SOMClass. 

We recommend, but do not require, 
that you use somPrintf() instead of 
printf() for output as shown in line 16. 
This ensures that any character redirec- 
tion will be properly handled across the 
board. 

Good programming manners 
requires that you free all of your objects 
at the end of your program. This is 
accomplished through the use of _som- 
Free(), as shown in line 18. Invoking 
_somFree() on an object automatically 
invokes the somUninit() method that we 
overrode for this class. The code for the 
overridden somninit() is shown starting 
at line 47 in Figure 9. 

Running this program gives the out- 
put shown in Figure 11. 


A MORE ADVANCED 
PROGRAMMING EXAMPLE 

Now that we've created the Appointment 
class, we'll use it as a basis for several 
other classes. Recall that objects of 
Appointment have a date, a starting time, 
an ending time, a subject, and an ID. 

In this section we will derive two 
new classes from Appointment. The first 
derived class is Meeting, which has a loca- 
tion in addition to what it inherits from 
Appointment. The second derived class, 
ConferenceCall, contains a phoneNumber. 

We will then create a constructed 
class, AppointmentBook, which will con- 
tain a sequence of Appointments. When 
we have a sequence of objects of class 
Appointment, by the rules of inheritance 
any of the sequence can be either an 
object of class Appointment or some class 
derived from Appointment. Since both 
ConferenceCall and Meeting are derived 
from Appointment, any of these three 
classes can be an element in the 
AppointmentBook. 

In the process of discussing Appoint- 
mentBook, we will discuss one of the tem- 
plate types shown in Figure 5, sequence. 

The IDL file defining the Meeting 
class, mtg.idl, is shown in Figure 12. 
There are several points worth men- 


01 #ifndef mtg_idl 

02 #define mtg_idl 

03 

04 #include "“appt.id1" 

05 

06 interface Meeting : Appointment 
07 { 

08 attribute string location; 


09 // The location of the appointment. 


10 

11. implementation { 

12 

13 dllname = "apptbk.d11"; 


14 releaseorder: _get_location,_set_location; 


15 

16 // Method Modifiers 

17 sominit: override; 
18 somUninit: override; 


19 bufferize: override; 

20 

21 // Attribute Modifiers 

22 location : noset; 

23 

24 // Instance data 

25 string bp; // buffer used by bufferize method 
26 +}; 

27 3; 

28 


29 #endif /* mtg_idl +/ 


Figure 12. /DL file for meeting: mtg. idl 


tioning about this file. This class is 
derived from Appointment (see line 6), 
whereas Appointment was derived from 
SOMOb ject. The object code for this class 
will be stored in the same DLL file as 
the code for Appointment, since they both 
use the same dl lname clause (see line 13). 
The Meeting class adds one new attribute 
to those it inherits from Appointment; that 
attribute is location (see line 8). One 
new attribute yields two implied meth- 
ods, a set and a get, both reflected in the 
release order (see line 14). Since this 
attribute is a string, we want to write 
our own set method, as we did for the 
string attributes of Appointment. Thus we 
declare the attribute noset (see line 22). 
Because we also want to override the 
bufferize() method, we declare this 


method as override (see line 19). On line 
25 we have bp as the internal instance 
data to be used by the bufferize 
method. 

Figure 13 shows the method imple- 
mentation file for Meeting. As with 
Appointment, most of the file was auto- 
matically generated by the SOM com- 
piler with the command: 


sc -sc mtg 


The methods are very similar to the 
methods of Appointment, and require no 
further discussion. 

Figure 14 shows the IDL definition 
for the ConferenceCall class. The only 
substantive difference between this and 
the definition for Meeting is that now we 
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Welcome 


Everyone knows OS/2° gives you more applications to 
choose from. Now all you need is more space on your 
hard disk to load them all. Stacker® for OS/2 & DOS is 
your answer. Stacker lets you quickly and safely double 
the capacity of your FAT hard disk, so you can take 
full advantage of OS/2—and virtually any DOS, 
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iT | You can install Stacker in minutes. 
a With Express or Custom Setup, you can 
automatically compress the data on the 
, # drive or customize the Stacker configu- 
ration to fit your needs. And you can be sure your data is 
safe with the leader in disk expansion technology. In fact, 
over four million people worldwide already trust their data 


to patented Stacker LZS™ compression technology. ! e 
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Manager and 
Dual Boot con- 
figurations. And 
there’s full support 
for OS/2’s extended 
attributes, too. The AutoProtect™ feature detects disk errors at 
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optimal performance. 
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Figure 13. C code for meeting: mtg.c 


20 OS/2 DEVELOPER 








This just in. Applications Manager, best known as 
AM,” has just added OS/2° 2.1 support. We repeat, 
the flagship client/server application develop- 
ment software from Intelligent 
Environments is now available for 
OS/2 2.1 environments. 

For the latest-breaking devel- 
opments, we take you to corporate 
America, where AM and OS/2 offer 
a tried and tested mechanism for building 32-bit, 
multitasking, line-of-business client/server appli- 
cations. AM’s visual programming environment 
streamlines the development and maintenance of 
mission-critical client/server applications by teams 
of programmers. And Static SQL support makes 
AM a real headliner. 

This recent news is becoming quite a feature 
story. By interfacing with 
MMPM/2, included 
with OS/2 2.1, AM lets 
programmers employ 
innovative team 
development 
capabilities : 
like dynamically linked programming—simplifying : _ . = 
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documentation, into Windows™ 3.1 applications 
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‘iietaekins sitciance Sha Peckicn To order or to find out more about OS/2 2.1 or 
engine. AM, call 1 800 3-IBM-OS2. In Canada, call 
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#ifndef ccall_idl 
#define ccall_idl 





#include “appt. idl” 


interface ConferenceCall : Appointment 


{ 
attribute string phoneNumber; 
// The phoneNumber of the appointment. 


implementation { 


dilname = “apptbk.d11"; 
releaseorder: _get_phoneNumber ,_set_phonelumber ; 


// Method Modifiers 
somInit: override; 
somUninit: override; 
bufferize: override; 


// Attribute Modifiers 
phoneNumber: noset; 


// Instance data 
string bp; // buffer used by bufferize method 


fendif /* ccall_idl */ 


Figure 14. Conference call definition: ccall.idl 
#define ConferenceCall_Class_Source 
#include <ccall.ih> 


#define BUF_SIZE 512 


SOM_Scope void SOMLINK _set_phoneNumber(ConferenceCall somSelf, 
Environment *ev, string phoneNumber) 
{ 
ConferenceCallData *somThis = ConferenceCallGetData(somSelf) ; 
ConferenceCallMethodDebug("ConferenceCall" ,"_set_phoneNumber") ; 


if(_phoneNumber != NULL){ 
SOMFree(_phoneNumber) ; 
_phoneNumber = NULL; 
} 
if(phoneNumber == NULL) return; 
-Phonellumber = SOMMalloc(strlen(phoneNumber )+1) ; 
strcpy(_phoneNumber, phoneNumber) ; 


Figure 15. Conference call implementation (continued on page 24) 
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inRegisterC lass(Parn, bAB, 7*® Anchor block hand! 
CPCH szhippNare, 7% Mare of class being registered “/ 
CPFME DiindProc, “* Window procedure for class “7 


c 


; 
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| add a phoneNumber attribute instead of a 


location attribute. 

Figure 15 shows the ConferenceCall 
implementation. This closely parallels 
the implementation of Meeting. 

Next we look at the definition of 
AppointmentBook. As we _ discussed, 
AppointmentBook can take a number of 
appointments, any one of which can be 
either an Appointment, a Meeting, or a Con- 
ferenceCall. Actually, our system is set 
using Appointment as a kind of general 
base class, and we assume actual 
instantiations will be either Meeting or 
ConferenceCall. 

The definition of AppointmentBook is 
shown in Figure 16. There are two new 
syntactic constructions we have not 
seen before: const and sequence. The const 
construction allows us to define a con- 
stant value. The sequence allows us to 
define a simple collection of items. 

The sequence is basically a C struc- 
ture containing three elements. One of 
the elements is a pointer to a buffer 
containing an array. Unless the 
sequence is of a simple type (such as 
short or long), the nth item of the 
array is a pointer to the nth thing in 
the sequence. The second element in 
the structure is the number of items in 
the array and the third is the size of 
the array. The size of the array minus 
the number of elements already in the 
array tells us the number of empty 
slots in the sequence. 

SOM automatically defines a set of 
macros that make it easier to manage 
sequences. They are: 

* sequenceLength(sequence), which 
returns the length of a sequence 

* sequenceMaximum(sequence), which 
returns the size of the array, 

® sequenceElement(sequence,n), which 
returns the nth element of the 
array. 

Since you will do most of your 

sequence access using these macros, the 

only sequence element you really need 

to know about is sequence._buffer, a 

pointer to the array containing the 

pointers to the sequence items. 

As you can see from Figure 16, 
AppointmentBook defines four methods. 


Environment 


} 
SOM_Scope void SOMLINK somInit(ConferenceCall somSelf) 
{ 
ConferenceCallData *somThis = ConferenceCallGetData(somSelf) ; 
ConferenceCallMethodDebug("ConferenceCall" ,"somInit") ; 
ConferenceCall_parent_Appointment_somInit(somSelf) ; 
_phoneNumber = NULL; 
_bp = SOMMalLoc(BUF_SIZE); 
} 
SOM_Scope void SOMLINK somUninit(ConferenceCall somSelf) 
{ 
ConferenceCallData *somThis = ConferenceCallGetData(somSelf) ; 
ConferenceCallMethodDebug("ConferenceCall", "somUninit") ; 
if(_phoneNumber != NULL){ 
SOMFree(_phoneNumber) ; 
_PphoneNumber = NULL; 
} 
ConferenceCall_parent_Appointment_somUninit(somSelf) ; 
} 
SOM_Scope string SOMLINK bufferize(ConferenceCall somSelf, 
*ev) 
{ 
string pbp; 


ConferenceCallData *somThis = ConferenceCallGetData(somSelf) ; 
ConferenceCallMethodDebug("ConferenceCall" , "bufferize"); 


pbp = ConferenceCall_parent_Appointment_bufferize(somSelf, ev); 
-bp = SOMRealloc(_bp, BUF_SIZE + strlen(pbp)); 
sprintf(_bp, "%sPhone Number: s\n", pbp, _phoneNumber) ; 


return(_bp); 


Figure 15. Conference call implementation (continued from page 22) 


addAppointment() takes an Appointment and 
adds it to the AppointmentBook. getDaysip- 
pointments() takes information about a 
particular date and returns a sequence 
of all the Appointments that occur on that 
date. Note that the sequence this 
method returns is a subset of the 
sequence attribute the AppointmentBook 
uses to internally manage its Appoint~ 
ments. 

The last method is deleteAppoint- 
ment(). You can delete an appointment 
by invoking deleteAppointment(), passing 


in the ID of the appointment to be 
deleted. The Appointment [D is actually a 
short integer that is one of the data ele- 
ments in Appointment. We have not 
talked about it much since its only pur- 
pose is to support the deletelppointment() 
method. 

In our implementation, shown in 
Figure 17, AppointmentBook is responsible 
for assigning [Ds to Appointments. It does 
this by starting with zero and incre- 
menting the ID of each Appointment as it 
adds it. Notice that the AppointmentBook 
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a 8 }lso contains a short attribute named 


#ifndef apptbook_idl 
#define apptbook_idl 


#include <appt.idb> 
interface AppointmentBook : SOMObject 
{ 
const short APPOINTMENTS_INCR = 16; 
attribute sequence<Appointment> appointments; 
short addAppointment(in Appointment newAppointment) ; 
// Add an appointment to the book. 
// Returns an appointment number. 
sequence<Appointment> getDaysAppointments(in short year, 
in short month, in short day); 


// Return a sequence of the given day’s appointments. 


void deleteAppointment(in short appointmentNumber) ; 


Figure 16. AppointmentBook definition: apptbook..idl (continued on page 28) 
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apptId that keeps track of the last 
assigned Appointment ID. 

The first method in the implemen- 
tation file is addAppointment(). It is 
passed an Appointment, updates the ID 
of the Appointment, and then adds the 
Appointment to the appointments sequence. 
The only difficult part of adding the 
Appointment to the sequence is dealing 
with a situation in which the sequence 
is already filled. In this case, we reallo- 
cate the buffer size to be large enough 
for an additional APPOINTMENTS_INCR 
number of appointments and reset the 
sequenceMaximum. 

The next method in the implementa- 
tion is getDaysAppointments(), which starts 
by allocating a sequence large enough 
to hold all the appointments in a given 
day. It then checks each element of the 
appointments sequence and, if the date of 
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// Delete the given appointment from the book. 


attribute short apptId; 
// Appointment book id generator. 


implementation { 


dilname = "apptbk.d11"; 

releaseorder: addAppointment,getDaysAppointments, 
deleteAppointment, 
_get_appointments,_set_appointments, 
_get_apptId, _set_apptId; 


// Method Modifiers 
sominit: override; 
somUninit: override; 


// Instance data 
sequence<Appointment> daysAppointments; 


#endif /* apptbook_idl */ 


Figure 16. AppointmentBook definition: apptbook..idl (continued from page 2/) 


#define AppointmentBook_Class_Source 


#include <appt.h> 
#include <apptbook.ih> 


SOM_Scope short SOMLINK addAppointment( 
AppointmentBook somSelf, Environment *ev, Appointment newAppointment) 
{ 


AppointmentBookData *somThis = AppointmentBookGetData(somSelf) ; 
AppointmentBookMethodDebug("AppointmentBook" ,"addAppointment") ; 


/* Generate an id for the newAppointment. 


wasa--- 2-2-2 2- n= === 2-2 -a=-====-=-=--=- ¢/ 


_apptid++; 
Appointment__set_apptId(newAppointment, ev, _apptId); 


/* Insert newAppointment into the book. 


wanna nn nn nnn nn nnn nnn nnn nn nnnnnnnnn= +/ 


if (sequenceLength(_appointments) == sequenceMaximum(_appointments)) { 
sequenceMNaximum(_appointments) += APPOINTMENTS_INCR; 
_appointments._buffer = (Appointment *) 
SOMRealloc(_appointments._buffer, 
sizeof (Appointment) * sequenceMaximum(_appointments) ); 


sequenceElement(_appointments, sequenceLength(_appointments)) = 
newAppointment; 
sequenceLength(_appointments)++; 


return(_apptId) ; 


Figure 17. AppointmentBook implementation (continued on page 30) 
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Figure 17. AppointmentBook implementation (continued on page 31) 
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AppointmentBook_parent_SOMOb ject_somInit(somSelf) ; #include <som.h> 
#include <appt.h> 
-apptid = 0; tinclude <mtg.h> 


appointments. buffer = (Appointment *) 
SOMMalloc(sizeof(Appointment) + APPOINTMENTS_INCR) ; 

-sequenceMaximum(_appointments) = APPOINTMENTS_INCR; 

sequenceLength(_appointments) = 0; 


#include <ccall.h> 
#include <apptbook.h> 


_daysAppointments._buffer = (Appointment *) : aa 
 SOMMalLoc(sizeof (Appointment) * APPOINTMENTS_INCR) ; #ifdef __IBMC__ 
} #pragma linkage 
(SOMInitModule, system) 
#endif 


ve eas void SOMLINK somUninit(AppointmentBook somSelf) 
AppointmentBookData *somThis = AppointmentBookGetData(somSelf) ; 
‘int. 1; 
AppointmentBookMethodDebug("AppointmentBook","somUninit") ; 


SOMEXTERN void SOMLINK SOMInitModule 
(long majorVersion, 


for (i=0; i<sequenceLength(_appointments); i++) { long minorVersion) 
SOMFree(sequenceElement(_appointments, i)); { 





i AppointmentNewClass(0,0) ; 

‘SOMFree(_appointments._buffer); MeetingNewClass(0,0); 

SOMFree(_daysAppointments._buffer); ConferenceCallNewClass(0,0): 
AppointmentBookNewClass(0,0); 


AppointmentBook_parent_SOMOb ject_somUninit(somSelf) ; 


Figure 17. AppointmentBook implementation ee from page 30) 
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Figure 18. initmod.c 
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the Appointment matches the requested 
date, copies it into the sequence it will 
return. 

The next method is deleteAppoint- 
nent(). We delete by appointment ID. 
The method looks through the appoint- 
ments, searching for one whose ID 
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matches the parameter. When found, it 
is deleted from the sequence and the 
other elements of the sequence are 
pushed together to remove blank 
space. 

The next method is somInit(), an 
override of one of the methods inherit- 
ed from SOMObject. This method first 
invokes the somInit() of its base class 
and then intializes its own instance 
data. _apptId is initially set to zero; 
newly added appointments, therefore, 
start with ID zero. Following this, the 
array portion of the appointment 
sequence maintained by this class are 
allocated to an initial size of APPOINT- 
MENTS_INCR elements. 

The next method is somUninit(), 
another override of one of the SOM0b ject 
methods. This goes through appointments 
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#include <appt.h> 
#include <apptbook .h> 
#include <mtg.h> 
#include <ccall.h> 


#include <stdio.h> 
#define MAX_LENGTH 80 
#define MAX_BUFFER_SIZE 1000 


/* Prints a message and reads a line into buffer. 
ao nee nnn nn enn nnn nn eo = 2 = == «/ 


static void getLine(buffer, msg) 
char bufferle; 

char *msg; 

{ 


int i,c; 
somPrintf (msg) ; 
for (i=0; i<(MAX_LENGTH-1) && (c=getchar()) 
'= EOF && cl= “\n’; ++i 
bufferlie = c; 
bufferUie = “\0’; 
} 


void setUpAppointment(Appointment appt) 
{ 


char inputUMAX_LENGTHe; 
Environment +ev = somGetGlobalEnvironment( 


getLine(input, "Enter month > 
__set_month(appt, ev, atoi(input)); 





); 


getLine(input, "Enter day >"). 


_-Set_day(appt, ev, atoi(input)); 


getLine(input, “Enter year > 
__set_year(appt, ev, atoi(input)); 


getLine(input, “Enter starting time > 
_.set_start(appt, ev, atoi(input)); 


getLine(input, "Enter ending time > 
__set_end(appt, ev, atoi(input)); 


getLine(input, "Enter subject > 
_-Set_subject(appt, ev, input); 


} 
main () 
{ 
short id; 
short i; 
short day, month, year; 
Appointment appt; 


AppointmentBook apptBook = AppointmentBookNew(); 


_IDL_SEQUENCE_Appointment apptList; 
char menuUMAX_LENGTHe; 

char inputUMAX_LENGTHe; 

string buffer; 

string menuLine = 


"\nm(meeting) c(conference) r(remove) d(display) q(quit) > "; 


mys 


gt fs 


fi 


mys 


Environment #evy = somGetGlobalEnvironment(); 


dof 


/* Display the menu options and read the operation. 
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Figure 19. Client program (continued at right) 


32 


getLine(menu, menuLine) ; 


/* 


/* 


\n" j 


| * 


j* 


| 


switch(menu0e){ 


Set up a meeting. 


case “m’: 

appt = MeetingNew(); 

setUpAppointment (appt) ; 

getLine(input, "Enter location >"); 

__set_location(appt, ev, input); 

id = _addAppointment(apptBook, ev, appt); 

somPrintf ( 

"Appointment id for this meeting is : {d \n", id); 

break; 


Set up a Sontanenge call. 


case “c’: 
appt = ConferenceCallNew(); 
setUpAppointment (appt) ; 
getLine(input, “Enter phone number I: 
__set_phoneNumber(appt, ev, input); 
id = _addAppointment(apptBook, ev, appt); 
somPrintf ( 

"Appointment id for this conference call is : Yd 


id); 
break; 


Remove an appointment. 


case ‘r’: 
getLine(input, "Enter appointment id > "); 
id = atoi(input) ; 
_deleteAppointment(apptBook, ev, id); 
break; 


Display the sss ies for a given day. 


case “d°: 

getLine(input, "Enter appointment month > "); 

month = atoi(input); 

getLine(input, "Enter appointment day > "); 

day = atoi(input); 

getlLine(input, "Enter appointment year > "); 

year = atoi(input); 

apptList = _getDaysAppointments(apptBook, ev, 
year, month, day); 

for (i=0; i< sequenceLength(apptList); i++) { 

buffer = _bufferize(sequenceELement(apptList,i), ev); 
somPrintf("\nis", buffer); 


break; 


Clean up and exit. 
------------------ +/ 
case “q’: 

break; 


} 
} while (menuU0e != “q’); 
_SomFree(apptBook) ; 


Figure 19. Client program (continued from left) 
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sequence freeing each element and, 
finally, the buffer itself. It also frees the 
sequence buffer used to return a day’s 
worth of appointments. 

The last piece of code needed to 
implement a class library is the SOMInit- 
Module procedure, one of which must be 
implemented for each class DLL. 
SOMInitModule is called by SOM after it 
dynamically loads your DLL. This 
function is expected to initialize your 
class library. The SOMInitModule proce- 
dure must call the classname NewClass 
procedure of each of the classes imple- 
mented in your DLL. Our SOMInitModule, 
shown in Figure 18, calls the NewClass 
procedure of each of our appointment 
book classes. 

Figure 19 shows a client program 
working with an appointment book. 
The main program is a loop following 
the algorithm: 


set up appointment book; 


do { show them what they can do; 
ask what they want to do; 
if (they want to set up meeting) 
create meeting appointment; 
if (they want to set up conference 
call) create conference call; 
If (they want to delete an 
appointment) delete appointment; 
If (they want to display a days 
appointments) show days appoint- 
ments; 

} while (they are not done) 


The most interesting part of the 
code is the display of the day’s 
appointments. We go through the 
sequence asking each element to 
bufferize itself, then print out the 
resulting buffer. Notice how this 
depends on a polymorphic resolution 
of the method bufferize(). 

The make file that creates both the 
client program (named SAMPLE.EXE) 
and the class library (named APPT- 
BK.DLL) is shown in Figure 20. The 
make file is designed to be easily adapt- 
ed to other SOM projects. 

Figure 21 shows the module 


definition file used to create the 
APPTBK.DLL. 

Figure 22 shows the output from 
one run of the program. We add a 
meeting and a conference call, then dis- 


play all appointments for 9/17/1993. 
Notice the polymorphic resolution of 
bufferize(), indicated by the fact that the 
first displays the location and the sec- 
ond the phone number. 
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OBJS = sample.obj 

TARGET = sample.exe 

DLLOBJS = appt.obj mtg.obj ccall.obj apptbook.obj initmod.obj 
DLL = apptbk 

CFLAGS = -Q+ -W3 -D__MIG_LIB__ -Ti+ 


LDFLAGS = = /packd /packc /exepack /align:16 /noi /m $(LDEBUG) /nol \ 
/PM:VIO /co 

SCFLAGS = -p -u -sh;ih;c 

cc = icc 

LIBLIST = $(SOMBASE)\lib\somtk 052386 


CORBASTYLE = $(SOMBASE)\include\somcorba.bld 


$(TARGET): $(CORBASTYLE) $(DLL).1ib $(OBJS) 
1ink386 $(LDFLAGS) $(OBJS), $*, $*/m, $(LIBLIST) $(DLL).1ib, nul 


$(DLL).d11: $(CORBASTYLE) $(DLLOBJS) $(DLL) .def 
1ink386 $(LDFLAGS) $(DLLOBJS), $@, $*/m, $(LIBLIST), $(DLL).def 


$(DLL).1ib: $(DLL).d11 
implib /nologo $@ $(DLL) .def 


~SUFFINES: .c .h .idl .ih .obj .csc 


c.obj: 
$(CC) $(CFLAGS) -Ge- -c $< 


.esc.ih: 
sc $(SCFLAGS) $#.csc 


.idl.ih: 
sc $(SCFLAGS) $*. idl 


.csc.h: 
sc $(SCFLAGS) $*.csc 


-idl.h: 
sc $(SCFLAGS) $*.id1 


clean: 
-del som.ir *.obj *.dl] *.lib *.exe #.map *.ih $(CLEANFILES) >nul 2>&1 


$(CORBASTYLE) : 
@echo This program requires the CORBA-style C bindings 
@echo created using the somcorba command. 
@exit 1 


appt.ih: appt.idl 
appt.obj: appt.ih appt.c 
mtg.ih: mtg.idl — 


ccall.obj: ccall.ih ccall.c 

apptbook.ih: apptbook. idl] 

apptbook.obj: apptbook.ih apptbook.c 

initmod.obj: appt.h mtg.h ccall.h apptbook.h 
sample.obj: sample.c appt.h mtg.h ccall.h apptbook.h 


$(CC) $(CFLAGS) -c $*.c 


Figure 20. lakefile 


SS ee = _ = 
LIBRARY apptbk INITINSTANCE 


DESCRIPTION “Appointment Book 
Class Library’ 


PROTMODE 


DATA MULTIPLE NONSHARED 
LOADONCALL 


EXPORTS 
AppointmentCClassData 
AppointmentClassData 
AppointmentNewClass 
AppointmentBookCClassData 
AppointmentBookClassData 
AppointmentBookNewClass 
ConferenceCallCClassData 
ConferenceCallClassData 
ConferenceCallNewClass 
MeetingCClassData 
MeetingClassData 
MeetingNewClass 


Figure 21. Module definition file 
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Manager’ code. It automatically generates C code, where 
you can link the graphic symbols to the application data 
they represent. This not only speeds up your development 
cycle, it also helps you create applications that are intuitive 
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m(meeting) c(conference) r(remove) d(display) q(quit) > m 


Enter month > 09 

Enter day > 17 

Enter year > 1993 

Enter starting time > 1015 

Enter ending time > 1100 

Enter subject > Marketing Meeting 


Appointment id for this meeting is : 1 


m(meeting) c(conference) r(remove) d(display) q(quit) > c 


Enter month > 09 

Enter day >17 

Enter year > 1993 

Enter starting time > 0900 

Enter ending time > 1000 

Enter subject > Product Planning 
Enter phone number > 512 111 2222 


Appointment id for this conference call is : 2 


m(meeting) c(conference) r(remove) d(display) q(quit) > d 


Enter appointment month > 09 


Enter appointment day > 17 
Enter appointment year > 1993 


(1) Date: 9/17/1993 Start: 1015 End: 1100 


Sub ject : Marketing Meeting 
Location : 70004 


(2) Date: 9/17/1993 Start: 900 End: 1000 


Subject: Product Planning 
Phone Number: 512 111 


m(meeting) c(conference) r(remove) d(display) q(quit) > q 


Figure 22. Program output 
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bject-oriented database management sys- 

tems are becoming widely used with many 

applications and operating environments. 
In fact, it is almost impossible to qualify the many 
types of applications for which object databases 
could have value. Early users have come from sev- 
eral key fields (primarily engineering design, 
telecommunications, and document management) 
but are now found in areas such as financial prod- 
ucts and process control reporting. In general, an 
object database may make sense for your applica- 
tion if some or all of the following criteria are met : 


Object-oriented databases integrate 
object-oriented language facilities 
with database capabilities such as 
persistence, concurrency, and integrity. 


1. Traditional DBMS technology has not been 
appropriate because of performance demands 
or programming complexity. 

2. The amount of information is large or complex 
enough that DBMS capabilities such as recov- 
ery /restart, transaction consistency, or nonstop 
operations are required. 

3. The application requires multiuser concurrent 
access to data at a finer granularity than that of 





A new generation of object-oriented database management systems, or ODBMS, meets the demands of com- 
pute-intensive applications such as engineering design (CAD, CASE, and so on), telecommunications, and com- 
plex document management. This article gives an overview of ODBMS and illustrates how existing applications 
can be migrated from OS/2 file-based storage to an ODBMS. BY MOHAMMED ANWARUDDIN 


Migrating From File-Based 
to Object Database Storage 
On OS/2 


an operating system file. 

The level of complexity of data-intensive appli- 
cations such as CAD, CASE, and Network Man- 
agement—and the data they manipulate—has 
grown beyond the capabilities of traditional data- 
base systems, which are record-oriented and limit- 
ed by a finite set of data types. 

Object-oriented languages are ideal for these 
applications because they offer extensible data- 
typing capability, which facilitates the storage of 
information not suitable for conventional databas- 
es. Through the object-oriented concept of inheri- 
tance, behavior and representation can be passed 
from one object to another. This allows code shar- 
ing among software modules and structure shar- 
ing among data objects. 

Object-oriented databases integrate these 
object-oriented language facilities with the data- 
base capabilities of persistence, concurrency, 
transactions, recovery, querying, versioning, and 
integrity. There are a number of approaches for 
integrating object-oriented capabilities into data- 
bases. One obvious approach is to extend an exist- 
ing object-oriented language with database capa- 
bilities. Integrating C++, for example, with these 
capabilities has several advantages: 

« C++ users can use the ODBMS with very little 
extra effort. 

e With a single type system, you can utilize the 
compile-time type-checking of C++ to provide 
type-checking for persistent as well as transient 
data. 

e You can use the full power of C++, including 
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virtual functions, inheritance, polymorphism, 
encapsulation, and parameterized types for 
application development. 

* It promotes reusability of code because the 
same code operates on either persistent or tran- 
sient data. More important, libraries developed 
for manipulating transient data can be used 
with persistent data without change. 

* No translation code is required to map the in- 
memory presentation of data to the disk-resi- 
dent representation, as is done in the file sys- 
tem storage paradigm. 

¢ It is easy to convert applications to use persis- 
tent objects. 

The example in this article, discussed in the fol- 

lowing section, focuses on many of the aforemen- 

tioned aspects of a C++ based ODBMS. 


MIGRATING AN EXISTING 

APPLICATION TO AN ODBMS 

The example we have chosen to illustrate the rela- 
tive ease of converting an existing application 
using an ODBMS is given using ObjectStore for 
OS/2 from Object Design, Inc. It is based on a code 
sample from an simple application that maintains 
a database of phone calls. (ObjectStore for OS/2 is 
the data management component of this C++ 
application written with C Set ++ from IBM and 
the OS/2 environment.) This setup is diagrammed 
in Figure 1. 

The original database, maintained in a flat text 
file, consists of data representing the total number 
of phone calls (volume) based upon the area code 
(ac) and the long distance carrier (1d). The function 
of the program is to: 
¢ Read in the database and create a binary tree 

representation, 

* Read a line of input and update the correct 
node in the tree, and 

¢ Write the tree structure back out to the flat file 
database. 

The program consists of three modules— 
update, read, and write. Figure 2 shows the main 
program, which constructs the in-memory data 
structure, reads input from a file, updates the 
correct node, and writes the translated data 
structure back to the flat file database. The read 
module (Figure 3) reads in the flat file database 
and creates the binary tree structure. The write 
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module (Figure 4) transforms the tree structure 
to the disk-resident representation and writes it 
back to the flat file database. Each node of the 
tree is an instance of the class node, defined in 
node.hh (Figure 5). 





Figure 1. Component technology 


The original application (Figures 2-4) is self- 
explanatory to C++ developers and won't be elab- 
orated on here. 

When this program is converted to work with 
ObjectStore (Figure 6), the binary tree structure can 


An existing application can be 
extended to a full object-oriented 
database management system. 


be written directly to the ObjectStore database, 
thereby eliminating the need for the read and 
write modules. That is, the binary tree structure is 
made persistent. 


THE MIGRATED APPLICATION 

Any application using ObjectStore functionality 
must first call the static member function ob ject- 
store:initialize() (line 4 of Figure 6). To create a 
persistent object, the database in which the object 
is to be stored must be specified. Before a persis- 
tent object is created, therefore, the database must 
be opened by calling the static member function 


reg3a 











database: :open() (line 5 of Figure 6). With 
ObjectStore, every read from or write 
to persistently allocated memory must 


- be within a transaction. The transaction 


macros have the form 


OS_BEGIN_TXN (identifier, exception**, 
transaction_type) and 
OS_END_TXN (identifier) 


In Figure 6, all persistent reads and 
writes are within the transaction t1. 

An object that has been stored in 
persistent storage is retrieved in sub- 
sequent processes by looking up the 
topmost (or entry-point) object by 
name and then by navigating to the 
target object. Line 7 of Figure 6 
retrieves a pointer to the database 
root named root and line 8 returns a 
pointer to the entry point object asso- 
ciated with the specified root. The 
program core (that is, statements 
within the scope of the while clause) 
remains unchanged from the original 
in Figure 1. The database is closed at 
the end of the transaction by calling 
the member function db->close() (line 
10 of Figure 6). 

Thus, the additional lines of code 
required to make this an ObjectStore 
application consist of calls to: 
¢ Open the database, 

e Start a transaction, 

¢ Find the entry point for the node 
data structure, 

e End the transaction, and 

¢ Close the database. 


BENEFITS OF MIGRATION 
The original application consisting of 
Figures 2, 3, and 4 is made up of 40 
lines of C++ code. The migrated appli- 
cation, shown in Figure 6, contains only 
28 lines, a reduction of 30%. In addition 
to substantial savings in coding, an 
ODBMS adds multiuser concurrency to 
a single-user application, transaction 
consistency with restart/recovery, and 
database administration capabilities. 
After migrating your C++ applica- 
tion, you can address areas of improved 
functionality. For example, you might 
wish to maintain versions of objects and 


#tinclude <stdio.h> 
#include "node.hh" 


extern nodet read_graph (char *); 


extern node* write_graph (node *, char *); 


main (int, char *#argv) 
{ 
node *#root, *ac_ptr, *ld_ptr; 
FILE *#fp; 

int ac, ld, volume; 


root = read_graph (argvU1e); 


Read in the flat file & create the binary tree --- */ 


/* ----- Read in the input & update the correct node in the tree -- */ 


fp = fopen (argvU2e, "r"); 
/* 


Core of the program. Walks a binary tree & updates 


an existing node in the tree. 


+/ 


while (fscanf(fp, "Ad 4d id", fac, Bld, &volume) != EDF) 


{ 
ac_ptr = root; 
while (ac_ptr->value != ac) 
ac_ptr = ac_ptr->sibling; 
id_ptr = ac_ptr->child; 
while (1d_ptr->value != 1d) 
1d_ptr = 1ld_ptr->sibling; 
ld_ptr->volume += volume; 

} 

fclose (fp); 


/* ---- Destroy the tree & save the file ---------- --- #/ 


write_graph (root, argvU1e); 
} 


Figure 2. Original C++ main program 


have the capability to merge them 
together at a later date if needed. Bidi- 
rectional relationships and collections 
facilities can be added to improve appli- 
cation performance and reliability. 

Of course, object databases vary sig- 
nificantly in their functionality and per- 
formance. When evaluating them, keep 
the following considerations in mind: 
¢ Performance in your application 


environment 
¢ Ease of use and programming 
¢ Ease of migrating existing applica- 

tions 
* Stability and track record of the 

vendor. 

Since the migration example above 
was based on the ObjectStore ODBMS, 
we will address some specifics of this 
database. 
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Figure 3. Read the flat database file and create tree 


OBJECTSTORE 

ObjectStore is a second-generation 
object-oriented database management 
system. Second-generation object-ori- 
ented database systems are based on 
C++, which provides most of the mech- 
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anisms needed to describe and manip- 
ulate persistent objects. Complete data- 
base functionality is obtained by addi- 
tional language and runtime features. 
ObjectStore databases can also be 
accessed by applications written in C. 


rsa3 


The product augments the language 


and runtime system to provide facili- 


ties for modeling objects and managing 
large sets of objects, including: 
* A collection facility (sets, lists, and 
so on), 
* Queries on collections, 
* Relationships between objects, and 
¢ Versioning of objects in support of 
groupware. 
ObjectStore provides a unified API to 
persistent and transient data, as well as 
traditional DBMS features such as per- 
sistence, transaction management, dis- 
tributed data access, and associative 
queries. It also supports the client/ 
server computation model, in which 
the server handles all access to Object- 
Store databases, including storage and 
retrieval of persistent data. The server 
is responsible for concurrency control 
and recovery; transactions involving 
more than one server are coordinated 
using the two-phase commit protocol. 
ObjectStore client libraries provide 
an interface between the user’s appli- 
cation and the server. The client man- 
ages the logical view of data including 
collections, queries, versions, transac- 
tion management, memory manage- 
ment, and relationships among objects. 
The client environment includes the 
ObjectStore Cache Manager, which 
maintains a cache of objects accessed 
by all the client processes on a machine. 
(A single cache manager handles the 
caches of multiple applications.) 
ObjectStore can address a database 
larger than the address space of the 
operating system by dynamically 
assigning portions of address space to 
correspond to portions of the databases 
used by the application. It provides 
three programming interfaces: C and 
C++ library interfaces and an extended 
C++ that provides a tighter language 
integration to the query and relation- 
ship facilities. 


IBM and OBJECTSTORE 

In 1993, Object Design and IBM signed 
a multi-year strategic relationship for 
developing and using object database 
technology, with IBM purchasing an 
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equity interest in Object Design. The a ce Re a 


two companies have since initiated sev- 

eral joint development projects. IBM #include <stdio.hh> 
Programming Systems will incorporate #include "node.hh" 
ObjectStore in several commercial 





applications involving document man- void write_graph (node *root, char *outfile) 
agement, groupware, and software { 

development. node #ac_ptr, *1d_ptr; 

CONCLUSION 


FILE *fp = fopen(outfile, "w"); 
ac_ptr = root; 
while (ac_ptr != NULL) { 


Object-oriented database systems hold 
promise for applications that deal with 
large amounts of non-record oriented, 


complex data. These systems integrate 1d_ptr = ac_ptr->child; 

object orientation with database capa- while (1d_ptr != NULL) { 

bilities, simplifying the modeling of fprintf (fp, "Ad 4d Ud\n", ac_ptr->value, 1d_ptr->value, 

real-world problems. ld_ptr->volume); | ac_ptr ->child = 1d_ptr->sibling; 
delete ld_ptr; 
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node( int val) { 

value = val; 

volume = 0; 

sibling = child = NULL: 


Figure 4. Write tree structure back to flat file 


Figure 5. Class definition file 
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Not long ago, client/server 
development required massive 
amounts of time, money and 
expertise to combine different 
anda complex technologies. 


~~ Now Digitalk 
PARTS 


PARTS, a rapid 
application 


too! set, lets you 
easily integrate 
m™ your software 





client/server applications. 

PARTS is the only object- 
oriented technology that lets 
you leverage your legacy code 
and the knowledge of your 
current staff. 

Only PARTS products let 
you take existing code —written 
in Smalltalk/V, COBOL, C, SQL 
and other languages — and wrap 
it into components or “parts* 
Which can then be virtually 


Snapped together visually. The result 


is smooth-running client/server 
applications in a fraction of the 
usual time. For a fraction of the 
usual cost. 

PARTS supports all popular 
SQL databases like Sybase, Oracle 
and DB2. Plus legacy or late mode! 
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systems like CICS, COBOL, APPC 
and SOM. And PARTS lets you 
develop on both OS/2 and Windows. 


RATED #1- TWICE. 


Only months ago, PC_ WEEK 
awarded PARTS Workbench the 
highest rating ever in the OS/2 


PARTS. THE CLIENT/SERVER INTEGRATION TOOL. 
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category, calling it “the defini- 
tive visual development tool” 

And InfoWorld ranked 
PARTS the #1 component- 
based tool for visual develop- 
ment. InfoWorld's Stewart 
Alsop adds: “There's nothing 
like it on the PC.” 

To make large teams pro- 
ductive, PARTS also supports 
group development and version 
control. Plus PARTS has a host 
of graphical power tools to give 
you all the power of objects - 
without the learning curve. 

10 YEARS EXPERIENCE. 

And PARTS is from 
Digitalk. The company that's 
been providing object-oriented 
tools to the Fortune 500 longer 
than anyone else in the world- 
with over 125,000 users. 

Call 800-531-2344 X 606 
and ask about our | 
PARTS Workbench 
Evaluation Kit. 

With minimum 
effort, you'll learn why 
PARTS is the maximum 
solution for client/server 
integration. 
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Figure 6. Migrated main C+ program 
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“WE BUILT THREE VERSIONS OF OUR APPLICATION TO RUN ON EIGHT PLATFORMS. 
THERE'S NO WAY WE COULD HAVE GOT THAT PRODUCT OUT WITHOUT SOFTWARE 
CONFIGURATION MANAGEMENT. I’D USE PVCS EVEN IF | DIDN’T WORK HERE.” 


If you're facing an assignment as tough as Jim’s, 
you're ready for The PVCS Series. 


If your development team has more than one member, 
your application has more than one module or you're 
working on a LAN—you need automated software 
configuration management. 


The PVCS Series is your best choice for LAN-based 
Software Configuration Management (SCM). We'll 
help you automate manual processes and avoid the 
headaches that multi-version, multi-module applica- 
tions can cause, 


You can skip the lost data, the bug fixes that don’t stay 
fixed, the builds that include outdated modules, 
overwritten code and the frantic midnight phone calls 
about wrong versions that somehow made their way 
into production. 


Instead of wasting time wrestling with your 
development environment, you can concentrate on 
building quality applications, regardless of what 
language, programmer workbench, methodology or 
operating system you're using. 


PVCS eliminates tedious housekeeping details and 
automates builds so they are consistent and error free. 
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PVCS gives you the security of project-wide undo 
and the confidence to create good code, knowing 
you've got a complete audit trail to show where you've 
been—and help plan where you're going. 


Operating seamlessly across Windows, NT, 

MS-DOS, OS/2 and a variety of UNIX environments, 
PVCS is flexible enough to fit your development style 
and the most complex new applications. 


The PVCS Series is the market leader in SCM for 
the LAN. It’s a complete family of products, designed 
for the widest variety of distributed client/server 
development architectures and operating systems. 


The PVCS Series includes: 

PVCS Version Manager, PVCS Configuration Builder, 
PVCS Production Gateway, PVCS Developer's Toolkit 
and PVCS Reporter. 


Put the power of The PVCS Series to work 
for you. Call for a free demo disk, evaluation, or a 
copy of the whitepaper, “Software Configuration 
Management: Choosing The Correct Interface”. 





The PVCS Graphical User 

Interface makes it easy to 
apply the power of PVCS 
in your distributed 
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Developer, September/October 1993) discussed how to create a threaded control. This article shows how to uti- 
lize the control within a Workplace object. BY CHRIS ANDREW, MARK A. BENGE, and MATT SMITH 


An Object of Many Colors: 
Using Custom Controls 
Within A Workplace Object 








Matt Smith 


n our previous article, we presented a 
threaded control that could be used to pick 
colors similar to those within the color 
palette of the Workplace Shell. In this article, we 
will show you how to use this control within a 
Workplace Shell object in order to create a Work- 
place class that you can utilize. Source code can be 
found on the usual electronic bulletin boards and 
on CompuServe, as detailed in the References sec- 
tion. 

The color wheel control we developed will now 
be utilized within a Workplace Shell object class, 
namely a color palette. This class is meant to illus- 
trate some of the principles of object-oriented pro- 
gramming, such as inheriting behavior from a par- 
ent object class, while at the same time illustrating 
that there is nothing magical about object-oriented 
programming or the Workplace Shell when inte- 
grating your own controls or those of the system. 

The new color palette provides a replacement 
object class for the system-provided color palette, 
with some enhancements to the original design. It 
shows how you can write other derivatives of the 
system-provided WPPalette object class to create 
an icon, bitmap, or other application-defined 
palette. Once you have grasped the simple con- 
cepts behind Workplace Shell programming, you 
should have no trouble creating your own object 
classes. 

We will also package our Workplace Shell 
object class into another custom control that can be 
used in any application, not just within the con- 
fines of the Workplace Shell itself. 





A BRIEF INTRODUCTION TO 
OBJECT-ORIENTED PROGRAMMING 
Object-oriented programming is a powerful tech- 
nique that allows applications to be developed in 
separate encapsulated units that frequently corre- 
spond to real-world problems modeled within the 
software. Each unit is known as an object class, and 
the functions that can be performed by an instance 
of that class are known as methods of the class. 
The object class also defines a data structure, which 
only the methods are allowed to manipulate, that 
exists for every instance of the object class. 

In other words, an object is merely a data 
structure that is manipulated exclusively by a dis- 
crete set of functions associated and instanced 
with that object's class, like that shown in Figure 1. 
The definition of the data structure and the func- 
tions that operate upon it is provided by its object 
class. Functions that manipulate an object are 
known as its methods; the variables within the 
data structure are often referred to as instance 
variables. 

The creation of a new object involves little more 
than allocating and initializing a new data struc- 
ture to represent the state of that object. Since the 
format of the data structure is defined by the class, 
the method used to create a new object (sometimes 
known as a factory method or, in C++, as the con- 
structor) is always provided by the class. Similar- 
ly, the destruction of an object (the destructor in 
C++) amounts to the freeing of that data structure 
once all the system resources that it utilizes have 
been cleaned up properly. 
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The only other thing you need to understand 
about object-oriented programming is how the 
principle of inheritance works—that is, how an 
object class can be written that inherits behavior 
from another object class. In the explanation up to 
this point, we have mentioned that the state of an 
object is uniquely described by a data structure 
contained within it. That data structure actually 
contains all the instance variables for all of the 
classes from which this object class is descended. 
Similarly, the object supports all the methods 
defined by all of the classes from which it is 
descended, in addition to whatever new methods 
it has defined. The key concept is that when an 
object class is defined it is able to add new meth- 
ods and override the existing methods defined by 
its parent classes. 


INVOKING A METHOD ON AN OBJECT 
DERIVED FROM TWO PARENT CLASSES 
Think of this in the same way as subclassing a 


window in PM. Obviously, after a window has 
been subclassed it still responds to the same PM 
messages it did before. However, there is no guar- 
antee it will respond in the same fashion to those 
messages. The subclass procedure is able to over- 
ride the processing of any message and can also 
add processing for new user defined messages. 

In PM there is no limit to the number of times a 
window can be subclassed, provided it is done 
properly. Each subclass is able to add or remove 
message processing from all previous subclasses 
of the window. It is also able to keep its own state 
variables for a window that has been subclassed in 
order to control its behavior. 

Object-oriented programming allows us to do 
exactly the same thing, but instead of adding or 
removing processing for a message we are modi- 
fying the behavior of a particular method of that 
object class. 

Now that we've briefly outlined the concepts 
of what happens behind the scenes in object-ori- 
ented programming, we can briefly discuss IBM's 
System Object Model and the way it has been used 
in OS/2 2.x. 


THE SYSTEM OBJECT MODEL (SOM) 
Most object-oriented programmers make use of an 
object-based programming language, such as C++ 
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Figure 1. Invoking a method on an object 


or Smalltalk, to develop object-orient- 
ed applications. These languages nor- 
mally come with a large library of pre- 
defined object classes that can be used 
as a starting point for deriving new 
object classes. 

When the Workplace Shell for OS/2 
2.0 project was started, there were no 
object-oriented languages capable of 
generating native 32-bit code. Given 
the object-oriented user interface of the 
shell, it seemed likely that the shell 
would have to be developed without 
the benefit of any object-oriented pro- 
gramming structure beneath the cov- 
ers. 

Fortunately, the System Object 
Model (SOM) technology that was 
being experimented with in the IBM 
AIX environment came to the rescue. 
SOM is really just a protocol that 
allows object-oriented classes to be 
defined in any programming language, 
even a procedural language such as C. 


LIBRARY YOURDLL 
DESCRIPTION “Your Controls DLL’ 


yourOrdiFunction 


Figure 2. Ordinal definition within definition file 


WinRegisterClass ( (HAB)NULL, 
"YourPublicClass", 
(PFNWP) YourWindowProc, 
CS_PUBLIC, 
sizeof (ULONG) + 
sizeof (PVOID)); 


Figure 3. Defining public class 


The elegance of SOM comes in its abili- 
ty to create a language-independent 
definition of the interfaces to a particu- 
lar object class, one that can then be 
used in any programming language. 
Thus it would be possible to develop 
an object-oriented application using 
SOM in which the object classes that 
comprised the application could be 
implemented in different languages. 

In OS/2 2.x, a SOM run-time sup- 
port DLL basically handles all the nas- 
ties of creating and destroying objects, 
making sure that the object classes con- 
form to SOM programming conven- 
tions. In the OS/2 2.x toolkit there is a 
SOM compiler that will take a lan- 
guage-independent definition of an 
object class (the .CSC file) and convert 
it into a set of skeleton functions and 
header files that can be used with IBM 
C Set/2, IBM C Set++, WATCOM 
C/C++32, Borland C++ for OS/2, or 
Zortech C++ for OS/2 compilers. 


WORKPLACE SHELL 
PROGRAMMING 

The Workplace Shell is implemented as 
a series of SOM object classes. The defi- 
nitions of these classes are shipped 
with the OS/2 2.x toolkit as a series of 


class definition files (.SC files in the 
\Toolkt21\SC subdirectory) and their cor- 
responding C syntax bindings (con- 
tained in .H files in the \Toolkt21\C\0S2H 
subdirectory). 

A common misconception is that 
SOM is used only with Workplace Shell 
programming. SOM is available for use 
with or without the Workplace Shell. It 
is important to note, however, that 
SOM (which comes with OS/2 2.x) 
does not yet provide any useful object 
class libraries of its own. It is really best 
used from another object-oriented pro- 
gramming language such as C++ that 
has its own set of ready-to-run class 
libraries and books full of sample pro- 
gramming techniques. 

Workplace Shell is run automatical- 
ly when the OS/2 operating system is 
started. The object classes that comprise 
the shell provide for the creation and 
destruction of persistent objects (objects 
that stick around even though they are 
invisible to the user) which can be 
stored as files or directories on the hard 
disk or, alternatively, stored in the 
OS2.INI file as binary data blocks. 

The Workplace Shell also uses the 
container and notebook controls to dis- 
play objects to the user as icons; the 
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This method allows the data contained within a particular cell of a palette object to be 


modified. Note that because the palette handles storage of the cell data automatically, 
any changes made to the cells of the palette are persistent. 


wpRedrawCell 


Forces a particular cell within the palette to be redrawn. Usually used in conjunction with 


the wpSetupCell method in order to allow the user to see changes in the palette as they are 


made. 


upPaintCell 


wpQueryPaletteInfo 


A palette subclass must override this method in order to display a graphical representation 
of the data contained within a given cell of the palette. 


Returns the current properties of the palette object, such as the number of rows and 


columns of cells and the size of the each cell element in pels. 


wpSetPaletteInfo 


This method may be called at any time to modify the number of cells within the palette or 


to set the dimensions of each cell displayed. Note that if the cells are of variable width or 
height, the maximum height and maximum width must be set using this method, or cell 
data could be clipped. 


wpEditCell 


When the user clicks on the Edit... push button at the bottom of the palette or double clicks 


on one of the palette cells, this method is invoked to bring up a value editing dialogue. 
Once again, all subclasses of WPPallete ought to override this method and invoke a suitable 


dialogue. 


wpQueryPaletteHelp 


This method should be overridden to tell the palette which panel to display when the user 


requests help (by pressing the Help push button in the palette window). 


woclsQueryEditString 


Table 1. Description of methods defined by WPPalette object class 


properties of those iconic objects are 
displayed in a settings notebook. In 
addition, the shell provides a set of 
defined method-based programming 
interfaces for the definition of the con- 
text menu, settings pages, object details 
to be displayed in Details view, and so 
on. 

One of the most important features 
of the Workplace Shell is that it is easily 
customized by the user, but still very 
extensible. Since even the system-pro- 
vided object classes can be modified to 
suit the purposes of the user, the shell 
is truly an open-ended application. 

To customize the Workplace Shell, 
you must write one or more SOM 
object classes, placing them within a 
DLL. You also have to register, using 
WinRegister0b jectClass, those object class- 


es with the shell so they can become 
part of the shell’s list of available object 
types. 

Because of the object-oriented 
design of the Workplace Shell, you 
don’t have to get involved in the usual 
PM programming chores such as creat- 
ing a message queue, variable storage, 
initialization, or using advanced fea- 
tures such as the container control, 
notebook control, or drag-and-drop. 
That functionality has already been 
written into the Workplace Shell; the 
associated behavior is inherited by all 
object classes. The only thing you must 
do is write the new behavior of your 
object class. 

As illustrated in the following exam- 
ple, it is possible to create a new object 
class that is implemented by fewer than 


Returns the text displayed in the Edit... push button in the palette view. 


a dozen lines of C source code. All its 
basic behavior is automatically inherit- 
ed from its parent Workplace Shell 
object class. 

The Workplace Shell provides an 
object class called WPPalette that pro- 
vides nearly all the functionality 
required to implement our ColorPalette 
object class. All instances of WPPalette 
are capable of storing a variable num- 
ber of data blocks, known as cells. 
Whenever the value contained within a 
particular data block gets modified, the 
palette object automatically saves that 
change back to its persistent form. In 
other words, we don’t have to worry 
about how or where to store the colors 
to be displayed by our palette. 

WPPalette also provides a view that 
shows a graphical representation of the 
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: tr Color Palette —- Palette =J}}| manages the creation of the window, Bi 
re . = | scrolling and positioning the cells to be 
displayed. The only code we have to 
write is a routine that displays the 
value contained by a given data block 
and tells the palette how much room is 
| il iil | required to draw each particular cell 
| i! eeeteeeeeeeteee {NUNN IIITIIII (the cells can be of different sizes). The 
vil | all eu WIHT palette view, shown in Figure 5, allows 

| aeceeeccrrroeseess) | TUNNIMIUIUTH INI | the user to drag a value from a cell so it 
can be applied to another window and 
also to edit the value of a given cell 
within the palette. We will completely 
override the method that edits a cell, 
displaying our own dialogue. This dia- 
logue, shown in Figure 6, contains the 
color wheel custom control that lets the 
user pick a color. We will allow the 
existing drag-and-drop functionality to 


be handled by our parent object class, 
| as it needs no modification. Table 1 
summarizes the purpose of the various 

‘| mew methods defined for WPPalette. 


In actuality, we will not be deriving 
Brag item to target window. Hold Alt our object class from the WPPalette class 

| . 7 ) but rather from the system-provided 
key for system default change. WPColorPalette class. We wish to inherit 
as much function as possible from our 
parent class, and WPColorPalette is the 
closest match to our desired functional- 
ity. Don’t believe that explanation? 
Okay, would you believe that we’re 
just plain lazy? 

The WPColorPalette object class con- 
tains all the code we will need to han- 
dle dragging and dropping colors from 
our palette. Each cell within an instance 
of the WPColorPalette object class is actu- 
ally a PAINTPOT structure in Figure 7. The 
first element of the cell data must 

= : ———$—$$_$—$<—<_—_ always be the CELL structure (contained 
Fig igure 6. Color picker | Haken roraaining aloe ial custom h control in the wppalet.h header within the 
\Toolkt21\C\0S2H subdirectory), which 
Es § Merely Contains a field describing the 
typedef struct size of the whole structure in bytes, The 
rest of the structure can contain any- 
thing (in this case, just an RGB value), 
but notice that each cell’s data does not 
have to be the same size. 

Now that we have discussed the 
basic functionality of the system-pro- 
vided color palette, we can consider 


Figure 7. Cell data used within a color palette what methods we need to override in 
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value of each data block. The palette [j cae’ — 


Hints And Tips From Von Den Workplace Hackmeister 
(Or, Confessions Of A Workplace Junkie) 


When developing a class, you may get tired of watching the Workplace Shell open all the 
windows you had open the last time. The automatic restart function can be disabled using 
the following options in your CONFIG.SYS file: 


SET RESTARTOBJECTS=NO 


We all make mistakes in our code, but the Workplace Shell is frequently very forgiving of 
serious mistakes: its exception handler just carries on to the next method call. The trouble 
is that this can be a hindrance during the development of an object class, when you'd love 
to know where your code is malfunctioning. Setting the following environment variable in 
your CONFIG.SYS file will turn off the exception handler: 


SET SHELLEXCEPTIONHANDLER=NO 


Many people experience problems when trying to compile and test an object class DLL. This is 
because the Workplace Shell loves to hang on to your object class DLL and keep it loaded 
until all instances of your object class have disappeared. There is, however, usually no need to 
reboot your system. The following hints can be helpful: 


Register your object class only once. The shell remembers that you have registered it, so 
you waste time if your de-register and register every time you modify your DLL. 


Create only one instance of your object class for testing purposes; put it in a folder that 
can be closed, so the usage count for your class DLL will be either one {if the object is vis- 
ible) or zero (if the folder containing it is closed). When the usage count for your DLL 
reaches zero, the shell will usually unload the DLL unless your object has class associa- 
tions to a filetype or file extension. 


To ensure that the Workplace Shell unloads your DLL as quickly as possible, use the fol- 
lowing environment variable in your CONFIG.SYS file: 


SET OBJECTSNOOZETIME=0 


lf these techniques aren't working for you, consider using a small program as a replace- 
ment for the Workplace Shell, such as the MYSHELL.EXE program provided with the 
source code. This allows you to start and stop the shell just like any other application. 
When it comes time to try another version of your DLL, just stop the shell, replace the DLL, 
and then restart the shell. 


We recommend kernel debugging to debug your object class, as you will be better 
equipped to understand when and how your methods are called because you have sym- 
bolic information for both the Workplace Shell DLL (PMWP.DLL) and the SOM.DLL (hey, we 
titled this “confessions of a hacker,” didn't we?). 


lf you are planning to use the kernel debugger, you will probably want to use the external 
prefix and class prefix operators in your .CSC files when you define your object class. This 


(continued on page 54) 
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our subclass, which we'll call Color- 
Palette. Since all object classes ought to 
identify themselves with a unique icon 
and also name themselves so the user 
can easily distinguish which category 
of object he or she is dealing with, it is 
advisable to override both the wpcls- 
QueryIconData and wpclsQueryTitle meta- 
class methods when creating a new 
Workplace Shell object class. 

Also, the wpclsInitData method has 
been overridden, so we are guaranteed 
to have registered the color wheel con- 
trol on the Workplace Shell process 
using the WinRegisterClass API. This is 
done because the wpclsInitData method, 
called only once when the class is 
loaded, is an ideal place to perform 
one-time initialization and window 
class registration. Otherwise, there is no 
real need to override any of the other 
standard Workplace Shell methods and 
we can concentrate on the palette meth- 
ods described in Table 1. 

For a start, we wish to override the 
wpEditCell method, so our object class 
will exercise the color wheel control 
created in our previous article. Over- 
riding this method will merely load up 
our ColorPickingDialog using WinLoadDlg if 
it hasn't been previously loaded. The 
user will then be able to modify colors 
in the palette using the color wheel 
control. Notice that the ColorPickingDia- 
log is non-modal, providing the easiest 
way for the user to change values of 
multiple elements of the palette very 
quickly. The user is free to choose 
another palette cell to be edited while 
leaving the ColorPickingDialog displayed. 

In addition, we are going to over- 
ride the wpPaintCell method to demon- 
strate how to draw the cell data. This 
isn’t strictly necessary, since our parent 
class WPColorPalette already draws each 
PAINTPOT as a circular splotch of color. It 
is, however, useful in illustrating the 
drawing model used within palette 
objects. To paint each cell, we will draw 
a filled polyline in its particular color 
using the GpiBeginPath, GpiMove, GpiPoly- 
line, GpiEndPath, GpiSetColor and GpiFill- 
Path APIs. The shape of the polyline fig- 
ure to be drawn will be defined by a 
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new method for our object class, which 
we'll call QuerySampleShape. 

When the user double clicks the 
mouse pointer on the square of color or 
clicks the mouse pointer on the Edit 
push button, the override wpEditCell 
method created earlier is called. 
Through this method, we communicate 


with the ColorPickingDialog using a pri- 
vate message MSG_EDITCELL. 

This message is given the current 
cell color and cell information, which 
allows it to set the cross hairs of the 
color wheel to the current color within 
the color palette swatch. It also 


allows—after the information has been 
saved within a private dialogue struc- 
ture—for user selection of the color 
wheel to be sent back to the color 
palette once the notification message 
has been received from the color wheel 
within the dialogue. 





STARCOLORPALETTE 

SAMPLE OBJECT CLASS 

To get back to a point made earlier, it is 
possible for an object class to inherit the 
behavior of every method defined by 
its parent class and write a very small 
amount of code to implement the new 


function you wish to add. As an exam- 
ple, consider the code in Figure 8 for an 
object class derived from the Color- 
Palette object class. All this derived 
class does is override the QuerySample- 
Shape method so the palette cell entries 
are drawn as star shapes instead of rec- 
tangles of color. Using the provided 
source code, try creating other simple 
subclasses of the ColorPalette object 
class. This will allow you to get familiar 
with the tools and processes needed to 
create Workplace Shell object classes. 


REXX INSTALLATION PROGRAM 
Once our object classes are written, the 
final step is to install them into the 
Workplace Shell and create some 
instances of those classes. This can be 
done through the WP Class List object 
shipped with the OS/2 toolkit, found in 
the PM Development Tools folder con- 
tained in the Toolkit 2.1 or Toolkit 2.0 
folders. It is, however, worth illustrating 
how easy it is to register and create 
object classes using a simple REXX com- 
mand file, as shown in Figure 9. 

Notice that the REXX procedure is 
able to specify various parameters to 
the palette objects using the setup 
string parameter. This technique is very 
similar to passing control data to a PM 
control window as it is created; howev- 
er, instead of a complex structure, the 
object setup string is just a series of 
key=value pairs separated by semicolons. 
All classes of Workplace Shell object 
support at least a few setup string key- 
words. For more examples, study the 
file INI.RC (installed on any OS/2 2.x 
machine in the \0S2 directory on the 
boot drive). This script file is used to 
create all standard objects that can be 
seen after OS/2 installation. 


COLOR SAMPLE CONTROL 

WINDOW CLASS 

Now that we've created a color palette 

object class that exists within the con- 

fines of the Workplace Shell application 

process, we will create a simple win- 

dow control that allows that palette 

functionality to be accessed from any 

application program in the system. 
The average OS/2 user is already 
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familiar with the concept of picking a 
color, font, or scheme from a palette of 
predefined values. So why not make 
that function available globally? 

When the user pushes the Edit 
Color... push button (like that in Figure 
10) displayed on the color sample con- 
trol, that control communicates with 
our Workplace Shell palette object class 
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Figure 8 C source code for 


so a view of the standard color palette 
appears. Having this functionality in 
several applications would allow the 
user to create a set of favorite colors, 
each stored within a single color 
palette—and then have easy access to 
them from any application. If a user is 
not satisfied with the colors that exist 
in the palette, he or she can always 
bring up the color picking dialogue 
and revise the color choices. 


CONTROL SAMPLE CODE 

The sample control will communicate 
with the Workplace Shell object, using 
the WinSet0bjectData API call to pass a 
setup string parameter from the appli- 


cation process where the control lives 
to the actual palette object (which lives 
under the Workplace Shell process). 
The method of creating the setup string 
parameter we'll use to get our palette 
to display itself is shown in Figure 11. 
It causes the shell to open the palette 
object in palette view or to resurface an 
existing open view of the palette. When 
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Pe Color Picker 


Figure 10. Color sample control 


the user picks a color, the palette then 
sends a notification back to the window 
handle to inform it of the new color 
choice. 

This allows users to pick colors from 
different applications using a single 
palette of colors. If at any time the user 
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decides that the palette doesn’t contain 
a suitable color, he or she just brings 
the color picking dialogue up to select 
another color into the palette. Neat, eh? 


COMING UP 

Beginning in our next article, we will 
implement a replacement to the list box 
control. Not only will the list box cir- 


cumvent the 64K limitation, it will be 
enhanced to allow for direct manipula- 
tion of text, columns, and other good- 
ies. So stay tuned over the next few 
issues while we develop the control 
into something you can use every day 
in your own programs. 
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here are now two kinds of OS/2 applica- 

tions: basic porting from the 16-bit world 

and the newer 32-bit SOM-integrated 
development. While the latter is the best way to 
write reusable code, it requires a deep redesign of 
applications to fully exploit object-oriented tech- 
nology. The guidelines offered in this article are 
an extract from OS/2 2.1 Workplace Shell Program- 
ming by Stefano Maruzzi. 

One of the distinctive features of OS/2 2.1 is 
the adoption of an object-oriented interface called 
the Workplace Shell (WPS), a complex multi- 
threaded OS/2 application automatically execut- 
ed as the system boots. WPS exploits the standard 
Presentation Manager (PM) API to create a com- 
plete window, window context menus, and other 
structural components. In addition, objects pro- 
vided by the System Object Model (SOM) of OS/2 
enrich the WPS interface. SOM is a tool to develop, 
package, and distribute objects among applica- 
tions. Every object class defined by WPS derives 
on a class, SOMClass, the ancestor of all objects in the 
system. WPS objects are placed in separate DLLs 
and developed according to the standard mecha- 
nism adopted for either EXE or DLL modules in 
the traditional PM programming scheme. 

Once a DLL is created, it is necessary to register 
itin WPS. The API function WinRegister0b jectClass() 
takes care of this operation, instructing WPS to 
load that specific DLL at every following boot. 
Similarly, WinDeregisterObjectClass() removes an 
object class from the WPS internal list. Almost 
everything found in the OS/2 System folder is an 


object (more specifically, an instantiation of an 





This article describes how to write Workplace Shell-compliant applications in C language, exploiting the API 
prototyped in PMWPH. BY STEFANO MARUZZ! 


Writing WPS-Compliant 
Applications 


object). The Color Palette, the Font Palette, and the 
Templates folder are objects based on WPS classes. 

Once opened, objects take the form of windows 
on the screen. From a user’s perspective, there is 
no way to distinguish between a WPS object and 
an application window. The title bar contains the 
window title, while the resizing icons to the right 
of the title bar let the user either hide or maximize 
the window. This is the result of mixing SOM 
objects and PM window classes. 


WHAT WPS IS 

Upon careful examination, WPS is basically a sub- 
classed window of class WC_CONTAINER. The parent 
window, a traditional frame without any frame 
control, is always hidden behind it. The frame's 
parent is the desktop, as shown in Figure 1. 

As stated earlier, one of the most publicized 
feature of OS/2 2.1 is its object-oriented interface 
(as compared to the application-oriented interface 
of MS Windows and OS/2 1.x), In Windows, drag- 
and-drop operations always start from File Man- 
ager where this undocumented logic is imple- 
mented. In WPS, in contrast, every object present 
in the shell is a valid source and target of a drag 
operation, with no preliminary discrimination. 
You can drag a document to either the printer or 
the shredder. The shredder itself can be dragged to 
a second level folder (a folder inside the desktop 
folder), and so on, 

From these direct manipulations, one can get 
the impression that drag-and-drop operations are 
system-wide. Although if you analyze WPS behav- 
ior from a user perspective this judgment is cor- 
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DESKTOP WINDOW 






Figure 1. Relationship between the desktop and WPS 


Figure 2. A client that is a window of one of the fifteen predefined window classes 


rect, from a PM developer's point of view, the 
focus is quite different. WPS, despite its role in an 
OS/2 system, is basically a traditional PM applica- 
tion with a frame window of class WC_FRAME and a 
client class, WC_CONTAINER. Everybody can achieve 
this goal by simply using WC_CONTAINER as the class 





HWND_DESKTOP 


WC CONTAINER 


name in WinCreateStdWindow(). In Figure 2, the identi- 
fier hwndClient refers to the container window. 

The net result is the absence of a window pro- 
cedure under developer control. The whole flow of 
messages generated by the user interactions direct- 
ly reaches the WC_CONTAINER window procedure; this 
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Notification Code = Value Description 

CN_DRAGAFTER 101 Sent to the owner after the receipt of a DM_DRAGOVER in the container with 
CA_ORDEREDTARGETEMPHASIS or CA_MIXEDTARGETEMPHASIS, and with a display mode 
of Name, Text or Detail. 

CN_DRAGLEAVE 2 Sent to the owner after the receipt of a DM_DRAGLEAVE. 

CN_DRAGOVER 103 Sent to the owner after the receipt of a DM_DRAGOVER and when the container does not 
have the attribute CA_ORDEREDTARGETEMPHASIS and is in the display mode Tree or Icon. 

CN_DROP 104 Sent to the owner after the receipt of a DM_DROP. 

CN_DROPHELP) =: 105 Sent to the owner after the receipt of a DM_DROPHELP. 

CN_ENTER 106 Sent to the owner after the pressing of the Enter key, or after a double- 
click with the selection button. 

CNLINITORAG § =: 107 Sent to the owner when a dragging operation is initiated. 

CN_EMPHASIS © 108 Sent to the owner when a record attribute changes in the container. 

CN_KILLFOCUS 109 Sent to the owner when the container loses focus. 


CN_SCROLL 110 Sent when scrolling takes place. 


CN_QUERYDELTA 111 Sent to get additional information when a scrolling is being executed. 


CN_SETFOCUS © 112 Sent to the owner when the container acquires focus. 


CN_REALLOCPSZ § 113 Sent to the owner before the editing phase of one of the container's items 
terminates (CN_ENDEDIT). 


CN_BEGINEDIT 114 Sent when a text string is being changed in the container. 


CN_ENDEDIT 115 Sent to the owner when the editing phase of one of the container's items 
terminates. 


CN_COLLAPSETREE 116 Sent after a tree structure is collapsed in the tree view display mode. 


CN_EXPANDTREE 117 Sent after a tree structure is expanded in the tree view display mode. 


CN_HELP 118 Sent to the owner after the receipt of a WH_HELP. 


CN_CONTEXTMENU 119 Sent to the owner when the container receives the message WH_CONTEXTMENU. 


Table 1. List of all notification codes for the WC_CONTAINER class 


system-wide operations instead take 
place inside the same container win- 
dow or in a parent-child relationship. 
According to the WC_CONTAINER naming 
convention, an object is a record (that 


is why the WPS client is subclassed. 
The detour in the flow of messages 
reaches first a window procedure 
inside the application and then the 
class window procedure where the 


container logic resides. 

If you consider WPS basically a 
WC_CONTAINER window, the judgment 
about the object-oriented interface 
changes drastically. All supposedly 
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is, a block of memory privately han- 
dled by the class). This chunk of memo- 
ry is composed of standard informa- 
tion, integrated by additional data spe- 
cific for that object. 

The classic distinctions in four object 
categories (folders, applications, data 
files, and devices) is, therefore, inap- 
propriate from a development point of 
view. They all are icons (records) inside 
one container, and the difference 
between the objects depends on the 
kind of data hooked to each one (object 
specific information). Every record ina 
container has some standard data (a 
RECORDCORE structure) containing basic 
information such as the image dis- 
played on the screen and its text. The 
developer adds to this data new infor- 
mation to better qualify a record. This 
is exactly what has been done in the 
development of WPS. 

Usually the object-specific data 
amount to a greater quantity than the 
size of a standard RECORDCORE structure. 
All this information is undocumented. 


DRAG-AND-DROP OPERATIONS 
IN A CONTAINER 

In every OS/2 demo, you have been 
shown how easy it is to drag a docu- 
ment on the printer or to destroy it by 
dropping it on the shredder. All these 
operations occur inside the same con- 
tainer window and are managed 
through DM_ messages and CN_ notifica- 
tion codes. OS/2 2.1 offers a set of sev- 
enteen messages specifically designed 
to describe every event related to drag- 
and-drop. These messages are always 
sent (they bypass the application mes- 
sage queue, reaching the destination 
window procedure directly) to the win- 
dow underneath the cursor hot-spot, 
and eventually to the target window. 
The WC_CONTAINER class, like any other 
predefined window class, has its own 
set of messages (CM_), window styles 
(CCS_), and notification codes (CN_). 
When an event occurs in a container 
window, the owner is notified via a 
WH_CONTROL message with the notification 
code packed in the second short in mp1. 
Some of the nineteen CN_ notification 
codes (the set is listed in Table 1) relate 





WPS. (PHSHELL EXE) PRESENTATION MANAGER 
int main(void) 
{ 


VinCreateStaindov( wale 
WinSubclassWindow(...): 


sy 


NRESULT EXPENTRY 
NewContainerWndProc(....) 
{ 


saith (ig) 
{ MRESULT EXPENTRY ContainerWndProc(...) 


{ 


} 

return (+pfnup)(hwnd, msg, mpi, mp2); 
returninDefWindowProc(...) 
} 





} 


Figure 3. Flow of messages for the WPS application 
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Figure 4. Data associated with each record object in a container window 
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specifically to drag-and-drop on a con- 
tainer window. 

To implement drag-and-drop in a 
container, it is sufficient to intercept the 
DM_ messages received in the target win- 
dow as a consequence of the call of 
DrgDrag() in the source application or to 
trap notification codes in the contain- 
er’s owner window procedure. Despite 
the complexity and the quantity of data 
involved, in many circumstances drag- 
and-drop refers to the same container 
window or strictly related window 
(another folder with a parent relation- 
ship to the WPS client window). Data 
comes from and reaches the same kind 
of object (i.e., a container). 

Subclassing a WC_CONTAINER window 
offers the opportunity to intercept all 
DM_ messages generated during a drag- 
and-drop manipulation. For WPS, all 
the CN_ notification codes reach the 
frame window procedure. To achieve 
this goal, you need only remember a 
simple though intriguing detail. By 
default, all the frame controls in a stan- 
dard window refer to the frame win- 
dow as their owner. This rule, howev- 
er, doesn’t apply to the client window, 
which has no owner. In WPS, the 
client’s owner is explicitly set to the 
hidden frame window to intercept all 
notification codes. This is a wise thing 
to do when the client is a window of 
one of the fifteen predefined window 
classes, as shown in the last portion of 
Figure 2. 

Based on this assumption, let's 
examine the information that reaches 
the frame window. Notification codes 
such as CN_DRAGINIT, CN_DRAGOVER, and 
CN_DROP contain in mp2 a pointer to some 
class-specific data structures like CNR- 
DRAGINIT (Figure 5) and CNRDRAGINFO. These 
structures are very simple and have 
few members. 

When the user starts dragging an 
object inside a container, its owner 
receives a CN_INITDRAG notification code, 
which collects valuable information in 
CNRDRAGINIT. The second member in CNR- 
DRAGINIT is a pointer to a RECORDCORE struc- 
ture (Figure 6), the data type where all 
record information is stored. 

Among the RECORDCORE members there 


typedef struct _CNRDRAGINIT 
{ // cdrginit 
HWND hwndCnr ; 
PRECORDCORE pRecord ; 
LONG x ; 
LONG y ; 
LONG cx ; 
LONG cy ; 
} CNRDRAGINIT ; 


typedef CNRDRAGINIT #PCNRDRAGINIT ; 


Figure 5. The CNRDRAGINIT data structure 


typedef struct _RECORDCORE 
{ // rece 

ULONG cb ; 

ULONG flRecordAttr ; 

POINTL ptlicon ; 

struct _RECORDCORE *preccNextRecord 
PSZ pszIcon ; 

HPOINTER hptrIcon ; 

HPOINTER hptrMinilcon ; 
HBITMAP hbmBitmap ; 

HBITMAP hbmMiniBitmap ; 
PTREEITEMDESC pTreeItemDesc ; 
PSZ pszlext ; 

PSZ pszName ; 

PSZ psztree ; 

} RECORDCORE ; 


typedef RECORDCORE *PRECORDCORE ; 
Figure 6. The RECORDCORE data structure 


typedef struct _CNRDRAGINFO 

{ // cdrginfo 
PDRAGINFO pDragInfo ; 
PRECORDCORE pRecord ; 

} CNRDRAGINFO ; 


typedef CNRDRAGINFO *PCNRDRAGINFO ; 
Figure 7. [he CNRDRAGINFO data structure 


are handles to icons and bitmaps to 
represent a record (object) on the screen 
in different views—icon, tree, and 
detail. This means that an application 
always knows the object aspect when 
dragging starts. Furthermore, the 
developer sets the object-related text 


Ba Se ee eee ee 
typedef struct _DRAGINFO 
// dinfo 
{ 
ULONG cbDraginfo ; 
USHORT cbDragitem ; 
USHORT usOperation ; 
HWND hwndSource ; 
SHORT xDrop ; SHORT yDrop ; 
USHORT cditem ; 
USHORT usReserved ; 
} 
DRAGINFO ; 


typedef DRAGINFO *PDRAGINFO ; 


Figure 8. /he DRAGINFO data structure 
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Figure 9. The DRAGITEM data structure 


DRAGINFO 


DRAGITEM 


DRAGITEM 


DRAGITEM 





Figure 10. Memory block allocated by an 
application system before executing a drag 


(i.e. the writing underneath the icon on 
the desktop) in the last three members. 

In Figure 7, we examine CNRDRAGINFO 
to understand how this information is 
passed to the target container (maybe 
the WPS window itself or an inner fold- 
er) after the user releases the right 
mouse button. 

This structure has a member of type 
PDRAGINFO, a pointer to a DRAGINFO struc- 
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ture, and a pointer to a RECORDCORE struc- 
ture. The access to a DRAGINFO data struc- 
ture provides all information related to 
a drag-and-drop operation in WPS, as 
shown in Figure 8. 

All data associated with the mouse 
during the dragging of one or more 
objects is packed in a memory block of 
variable size. At the beginning is a DRAG- 
INFO structure, followed by as many 
DRAGITEM structures as instructed by the 
cbDragIten member (Figure 9). Figure 10 
illustrates how information is stored by 
the source application before starting a 
drag process. 

Once again, even in the case of a drop 
onto a container window, WC_CONTAINER 
information and direct manipulation 
data are strongly related. The last three 
HSTR members contain useful informa- 
tion for the target window. The handle 
to the string in hstrContainerName refers to 
the source container. Considering that in 
OS/2 2.1 a folder is the equivalent of a 
directory in the file system, this means 
that the physical origin in the file system 
is always known by the target. 

The opposite is never true; right 
now there is no way for the source win- 
dow to find out where an object is 
placed. I’m referring specifically to 
when an object is either moved or 
copied between two WPS folders. The 
feedback provided by WPS is limited 
to a series of DM_DRAGOVERNOTIFY messages, 
with mp1 pointing to a DRAGINFO structure 
slightly modified according to the 
return value of the DM_DRAGOVER message. 
The source window of the direct 
manipulation gets the target window 
handle as the return value of DrgDrag(). 
From this point on, I have defined an 
empirical way to obtain the full path- 
name of the target destination of a pre- 
vious drag-and-drop. Once you have a 
handle, it is easy to query the window 
title. The first portion of it is the direc- 
tory name, from which you can jump 
back to the complete pathname. 

To summarize, in the case of a con- 
tainer window (despite the fact that the 
source and the target containers are 
either the same or different windows), 
the information provided through the 
notification codes (CN_) and direct 
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manipulation messages (DM_) offer a 
detailed view of what is happening in 
the system. 


DRAG-AND-DROP OPERATIONS 
WITH DIFFERENT WINDOWS 
Problems arise when you try to 
exchange information via drag-and- 
drop with another running application 
such as an editor. The worst situation is 
when the flow of information is from a 
WPS object to an application. In this 
case, a good portion of the information 
usually provided through a RECORDCORE 
data structure is no longer available 


Even in the case of a 





drop onto a container 


window, WC_CONTAINER 
information and direct 


manipulation data are 
strongly related. 


because the target application is not a 
window of class WC_CONTAINER and the 
two processes don’t share the same 
address space. 

On the other hand, when the source 
of information is an application and the 
target is WPS, you need only prepare 
the DRAGINFO and DRAGITEM structures 
according to what WPS expects (revert- 
ing to DrgDragFiles(), as in the copy of 
multiple files, doesn’t require filling in 
any DRAGxxx data structure). The internal 
support to drag-and-drop is limited to 
container windows, a big disadvantage 
because one objective is to write WPS- 
compliant applications that are well 
integrated in the system shell. The solu- 
tion to this problem lies in writing spe- 
cific code inside each application that 
makes it drag-and-drop aware. 

Despite this lack of truly system-wide 
object management tools, a smart devel- 
oper can bypass this limitation with a 
hint of imagination and some experi- 
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ence. This result can be achieved by writ- 
ing plain C code and interacting with 
WPS objects as if they were windows. I 
always spend a lot of time trying to 
design an intuitive user interface to my 
applications; in one case, I designed a 
kind of panel window that was original- 
ly empty. Its surface is divided in two 
columns and six rows (both dimensions 
are variable). Each cell of the panel can 
accept an object represented as an icon. 
The user selects one object from the 
desktop and drops it in on empty cell. 
The result is shown in Figure 11. 

The PANEL application is basically a 
valueset window, one of the five new 
predefined window classes added with 
the introduction of OS/2 2.x. Like the 
WC_CONTAINER class, WC_VALUESET has some 
specific notification codes related to 
direct manipulation. While it is easy to 
understand that a drag is occurring (a 
valueset receives the standard DM_ mes- 
sages), when the user releases the right 
mouse button there is no RECORDCORE data 
structure to supply all that valuable 
information. To obtain the object icon 
in that case, I refer to WinLoadFileIcon(), a 
new API prototyped in PMWP.H. This 
function loads an application icon from 
different sources (but doesn’t always 
work properly). This is exactly what 
WPS does in the General page in Note- 
book Settings when changing the object 
icon via drag-and-drop. 

The code quality of applications 
such as PANEL would greatly benefit 
from better-documented WPS behav- 
ior. Considering that every program 


ed as an icon 


has to interact with WPS, knowing how 
the system shell responds to every 
event is a primary need. 


Conclusion 

OS/2 2.1 offer a broad range of tools to 
develop easy-to-use applications. The 
key components are drag-and-drop 
support and an extensive use of WPS 
objects (with the addition of new class- 
es). If developers follow this approach 
to the use of WPS objects, a set of new 
and exciting applications will fully 
exploit the power of OS/2 2.1 in the 
near future. 





Figure 11. Panel window in which each cell of the panel can accept an object represent- 
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This article describes IBM's microkernel technology, examining its architecture and associated programming 
abstractions. It also describes how the microkernel can be used as the foundation for a highly modular, portable, 
and secure operating system that can support multiprocessor and multiple operating system personalities. 

BY PYLEE LENNIL 


The IBM Microkernel 
Technology 


he IBM microkernel technology is based ona 
Mach microkernel originally developed by 
Carnegie Mellon University. It also contains 
selected technologies developed by the Open Soft- 
ware Foundation Research Institute, as well as func- 
tionalities implemented by IBM. The major features 
of the microkernel can be summarized as follows: 
* Simplified architecture 
® Expandability 
* Portability 
* Multiprocessor support 
* System security. 
The microkernel provides a simple, highly modular 
and extensible architecture compared to a tradition- 
al operating system kernel. Extensibility allows 
many traditionally kernel-based operating services 
to reside outside the kernel at the user process level. 
In the traditional operating system, services such as 
process management, virtual memory manage- 
ment, network management, file system services, 
and device management are all built into the kernel. 
This results in a cumbersome and inflexible kernel 
that is difficult to enhance or port to different hard- 
ware platforms, These system kernels also normally 
support uniprocessor and are inherently less secure. 
The microkernel, on the other hand, is highly 
secure. It provides only basic system services such 
as task and thread management, interprocess com- 
munication, virtual memory services, I/O, and 
interrupt services. These services are made avail- 
able to user-level tasks through a set of microkernel 
interface functions. The small kernel also facilitates 
real-time support, as only a minimum of kernel 
code must be executed. 
Unlike in a traditional operating system, services 


such as file system, network services, and device 
drivers operate outside the microkernel as user- 
level servers, as shown in Figure 1. The clean sepa- 
ration of kernel servers reduces complexity, increas- 
es portability and requires fewer entries into the 
kernel level to perform operating system functions. 
In addition, the servers allow the creation of a high- 
ly modular operating system that can support mul- 
tiple system personalities and services by configur- 
ing them as user-level servers. 

The microkernel is easily portable to different 
computer platforms due to the clean separation of 
machine-dependent and machine-independent 
code. Machine-dependent and device-dependent 
code is located in the microkernel; porting to a new 
hardware platform mainly involves rewriting the 
machine-dependent code. 

The traditional operating system kernel is not 
very secure, with security features built outside the 
kernel. The microkernel, on the other hand, is 
designed weith security as an integral feature of the 
system. The microkernel operates on system 
resource objects such as virtual memory space, files, 
and processors. User-level tasks access these objects 
by sending messages through highly secure com- 
munication channels called ports. 

In a traditional operating system, device dri- 
vers operate at the privileged level. Under the 
microkernel, however, they operate at the user- 
process level, above the kernel. This means that 
device drivers can be developed and debugged 
just like user programs; this also increases porta- 
bility into other hardware platforms. Since the 
device drivers are priviedged microkernel tasks, 
they get access to I/O resources such as I/O ports, 
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memory-mapped devices, and direct memory 
access (DMA) through the microkernel services. 
Interrupts are normally intercepted by the micro- 
kernel, which decides whether to handle the inter- 
rupt or send it to the user-process level device dri- 
vers. These drivers must be registered with the 
microkernel and must maintain interrupt handlers 
waiting to service the interrupts. 


MICROKERNEL ARCHITECTURE 

The microkernel provides the following program- 
ming abstractions, from which other operating sys- 
tem functionalities can be derived: 


Task. A program running under the microkernel is a 
task. Each task owns a collection of resources such as 
virtual address space, threads, and ports. The micro- 
kernel provides each task with protected access to 
system resources through ports, communication 
channels maintained by the microkernel. A task can 
communicate with other tasks through ports. In a 
client/server environment, a client task can request 
services from a server task using interprocess com- 
munication. Tasks may be created, terminated, sus- 
pended, or resumed by other tasks. When a new task 
is created, it can inherit virtual address space and 
port capabilities from its parent task. 


Thread. A thread is the smallest independent unit 
of execution (instruction stream) running within 
a task. Each task requires at least one—possibly 
more—concurrently executing threads to perform 
a computation. Threads share the task address 
space and all other task resources such as virtual 
memory, file descriptors, and ports. Threads are 
scheduled to a processor by the microkernel, 
which allows multiple threads to run concurrent- 
ly within a single task’s memory space. For exam- 
ple, a multithreaded program may use one thread 
to compute a mathematical formula while anoth- 
er is used to receive user input. Multithreaded 
tasks provide programs with greater performance 
and modularity. In uniprocessor environments 
the use of threads increases the performance of 
the task by overlapping the execution of the com- 
putation and I/O threads. In a symmetric multi- 
processing environment (one in which processors 
share the same physical memory), the microker- 
nel allows threads in a multithreaded program to 
execute in parallel on different processors. This 


results in substantial improvement in the task’s 
performance. 


Objects. The microkernel is object-oriented in 
nature. All microkernel services and resources such 
as tasks, threads, virtual memory regions, files and 
processors are represented as objects. Each object 
provides a set of operations that can be invoked by 
sending messages to that object, which in turn 
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invokes the functions that correspond to each oper- 
ation. For instance, data can be read from a memo- 
ry object by sending a message to that object. When 
a task creates an object, it receives a port name, 

which represents the object, and port rights, which 
give the task restricted access rights to the object. 

The object concept can also be extended into a net- 
work environment, where objects can exist on any 
system in the network. A task can transparently 
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Figure 1. |BM’'s microkernel-based operating system structure (reprinted from |BM Micro- 
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invoke these remote objects using inter- 
process communication. 


Ports, Ports are communication channels 
used to send and receive messages 
between two tasks. The port is the basic 
object reference mechanism; it can be 
used to invoke operations on objects 
such as virtual memory regions, files, 
processors, tasks, and threads. A port is 
a queue managed by the microkernel, to 
which messages from a sender task are 
appended by a Send operation. The mes- 
sages are then taken out by a recipient 
task through a Receive operation. Ports 
are protected by a capability mechanism 
so that tasks with appropriate send and 
receive capabilities can access them. This 
means that only a task with receive 
rights can obtain messages sent to a port 
and only tasks with send rights can send 
to it. Tasks can create ports for their own 


use; to establish communication with 
other tasks, they may also send port 
capabilities to other tasks with mes- 
sages. Furthermore, using network 
servers, port capabilities can be extend- 
ed transparently over a network to 
invoke objects residing on different sys- 
tems. Port capabilities are highly secure 
because they are hard to forge or create 
fraudulently. 


Interprocess Communication. Interprocess 
communication (IPC) is a mechanism 
that allows communication between 
two tasks. IPC uses messages to pass 
information between tasks; a task sends 
a message to a port and another task 
receives it from the port. A message con- 
sists of a fixed length header followed 
by a collection of data including port 
capabilities and references. Messages 
can be exchanged using blocking or 
non-blocking communication. In the 


case of blocking communication, the 
message is transferred directly to the 
receiving task when it invokes the 
Receive operation. For nonblocking com- 
munication, the message is passed in 
two stages, first from the sender to the 
kernel and then from the kernel to the 
recipient. IPC also supports the 
client/server computing environment 
by allowing communication between 
tasks running on different networks 
through message servers. 


Virtual Memory. Microkernel virtual 
memory support provides large paged 
address spaces to the tasks. The micro- 
kernel supports the concept of memory 
objects when using the virtual address 
space. It manages the physical memory 
as a collection of memory objects, which 
can be mapped into a task’s virtual 
address space. A memory object can be 


The IBM microkeme! technology is based on a 
Mach microkemel originally developed by 
Camegie Mellon University. 


a virtual memory page, a set of pages, or 
a secondary storage object such as a file. 
A file object mapped into the address 
space can be read or written like a nor- 
mal memory object. When a process ter- 
minates, its mapped file objects are 
automatically stored back into the file 
system with all changes. You can associ- 
ate a port with each memory object. 
Ports can be used to send messages to 
the memory object in order to request or 
transmit memory object data. 

The microkernel allows a server task 
outside the kernel to manage virtual 
memory. This task, known as an exter- 
nal pager, has access to memory objects 
stored on a disk. When virtual memory 
is allocated, an external pager may be 
specified to handle paging requests. If 
no external page is specified, a default 
pager is used. 

The microkernel also allows tasks to 
share memory objects as well as transfer 


large amounts of data between tasks. It 
uses a technique called copy-on-write 
(lazy evaluation) that allows tasks to 
share memory objects without copying 
the pages associated with those objects. 
Initially, the pages to be shared are 
marked as read only. As long as the 
tasks make only read reference to these 
pages nothing is changed. A write to any 
of the pages generates a page fault; the 
microkernel creates new copies of those 
pages. The microkernel also provides a 
mechanism to efficiently transfer large 
amounts of data between two tasks. The 
sender task sends a pointer to the data 
area, called “out-of-line data,” to the 
receiving task. When the recipient 
receives the message, the microkernel 
simply maps the pages to the destination 
task’s address space, thus avoiding the 
physical transfer of data between tasks. 


Host and Processor Set. The host and 
processor set are functions used by 
applications that utilize advanced oper- 
ating system features. The host feature 
gives information about the processor 
complex running the system, as well as 
functions such as date, time, and sys- 
tem stop and restart. The processor set 
features are used in multiprocessor 
machines to group processors into 
classes. These classes allow a parallel 
application to execute multiple threads 
simultaneously on different processors 
in the machine to achieve true parallel 
execution. 


Server Tasks. The microkernel supports 
special application-level tasks called 
personality and personality-neutral 
servers that provide operating system 
personalities and services. There are 
two types of servers. Personality 
servers are used to create operating 
systems such as DOS, OS/2, and AIX, 
allowing multiple operating system 
personalities to coexist on a single 
machine. In contrast, traditional oper- 
ating system services such as file sys- 
tem, device, and network services are 
built into personality-neutral servers. 
For instance, the master server may 
load other personality servers and they 
all can share a common file system 
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server, device drivers, and default 
pager, as illustrated in Figure 1. The 
servers communicate with each other 
through ports via interprocess commu- 
nication. 


MICROKERNEL 

HIGH-LEVEL INTERFACES 

The microkernel provides two high- 
level program interfaces that help pro- 
grammers develop multi-threaded and 
client/server applications. 


Microkernel Interface Generator (MIG). 
Programs using microkernel inter- 
process communication often follow the 
client/server programming paradigm in 
which clients send a message to request 
services from a server and receive data 
via another message. To relieve the pro- 
grammer of the tedious task of setting 
up and sending messages, the microker- 
nel provides an IPC interface generator 
called MIG. MIG is a compiler that takes 
a specification of a message-passing 


The IBM microkeme! provides the core 
— technology for a next-generation operating 
system. 
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C Threads. The IBM microkernel pro- 
vides a set of low-level functions to cre- 
ate and manage multithreaded pro- 
grams. Using these low-level APIs gives 
complete control of a thread, but it also 
requires handling machine dependen- 
cies, requiring programmers, for exam- 
ple, to set up the state of a thread. The 
microkernel also provides a set of high- 
level C language interface functions 
called C threads that help users create 
multithreaded programs rather than 
using low-level thread functions. (These 
routines are contained in the C threads 
library.) A major benefit of the C thread 
functions is code portability; the library 
provides machine-independent func- 
tions to create and control threads. The 
C thread library also contains functions 
to coordinate multiple threads, shared 
variables, and mutual exclusion for crit- 
ical sections. This frees the programmer 
from developing complex thread syn- 
chronization mechanisms. 


interface and a procedure call interface 
and generates appropriate C language 
code for both client and server pro- 
grams. This eliminates the need for the 
programmer to implement the packing, 
sending, receiving, and unpacking of 
IPC messages. An additional benefit is 
that generating IPC code through MIG 
eliminates the chance for programming 
errors caused when code is written 
manually. 


CONCLUSION 

The IBM microkernel provides the core 
technology needed for the development 
of a next-generation operating system. 
Its multiple operating system personali- 
ty support allows applications written 
for different operating systems to be run 
concurrently on the same machine. The 
multiprocessor support allows applica- 
tions to achieve maximum performance 
from multiprocessor hardware. The rel- 
atively small kernel supports real-time 
applications. The ability to maintain and 
access objects over a network allows dis- 
tributed computing. Finally, the inher- 
ently secure and easily portable micro- 
kernel allows the creation of secure 
operating systems on a variety of hard- 
ware platforms. 


Pylee Lennil, /BM/ Corp., 1000 N.W. 51st 
St., Boca Raton, Fla. 33429, (407) 443-3855. 
Lennil joined IBM in 1983 and is an advisory 
programmer in the IBM entry systems tech- 
nology laboratory. He is presently involved in 
the development of OS/2 and spent several 
years in PC DOS and AlX development. He 
received a B.S. in physics from Kerala Uni- 
versity in India and an M.S. in computer 
engineering from the University of Massa- 
chusetts at Lowell 
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he PCMCIA standard has come a long way 
since the concept was first formulated in 
1989, Initially designed only for memory 
card devices, it has since grown to encompass I/O 
implementations such as modems, 3270, Token- 
Ring, and Ethernet cards. Originally supported by 
few manufacturers, PCMCIA has matured to the 
point where the IBM PS/2E desktop system is 
dependent on PCMCIA 
architecture. IBM hopes 
that PCMCIA software 
will make the same pro- 
gression. While other 
system manufacturers 
use PCMCIA heavily in 
notebook and laptop 
computers, IBM also | 
uses the cards in its 
desktop systems. | 
PCMCIA cards are 
distinct from standard 
PC adapter cards in 
several ways: 
¢ PCMCIA is its own 
bus; the cards are 
neither ISA bus nor PCMCIA card 
Micro Channel. 
¢ PCMCIA is nonproprietary; it is the same 
across IBM and non-IBM systems. 
¢ Memory and I/O registers for the card can be 
mapped into any available space on the host 
system; users needn’t deal with dip switches or 
system reconfiguration utilities. 
e The cards can be inserted or ejected while the 








While much has been written in the trade press about the Personal Computer Memory Card International Asso- 
ciation (PCMCIA), most articles tend to focus on POMCIA’s current capabilities. This article explores the cards’ 
potential, using on IBM PCMCIA Data/Fax Modem as an example. BY DANA BEATTY 


Programming PCMCIA: 
It’s All in the Cards 


system is running. 

¢ They are lightweight and easy to use. 

¢ Cards are completely encased; there is no need 
to worry about their ruggedness. 


UNTAPPED SOFTWARE POWER 
Because the proficiency of most PCMCIA manu- 
facturers is limited to the actual card hardware, 
most of the burden for 
| interoperability and 
usability of the devices 
has fallen on PCMCIA 
system and operating 
| system providers. In the 
last year, IBM began 
| shipping the key PCM- 
CIA software elements 
(socket services, card ser- 
vices, and client drivers) 
with its PCMCIA sys- 
tems, operating systems, 
and PCMCIA cards. 
Each of these software 
elements has a logical 
home. Figure 1 illustrates 
the PCMCIA software 
architecture. 


PCMCIA Software Architecture. Socket services, the 
lowest software layer, interacts directly with the 
system hardware chip that controls the PCMCIA 
socket. Socket services is concerned with tasks such 
as fielding interrupts generated when a card is 
inserted or ejected from a system. Because the chip 
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Figure 1. PCMCIA software architecture 


that supports the socket varies from system to sys- 
tem, socket services could reside in system BIOS; 
today, however, it ships with the system as a 
device driver or similar configuration. 

Card services communicate with socket ser- 
vices to provide a more generalized set of func- 
tions for managing PCMCIA cards. Card services’ 
main function is to manage and coordinate the use 
of system resources, such as IRQs and memory 
space, among all PCMCIA devices in the system. It 
provides a set of functions accessed by client dri- 
vers through its API. Because its implementation is 
operating system-specific, card services would 
most logically be shipped with the operating sys- 
tem, as IBM does with DOS 6.1 and OS/2 2.1. Cur- 
rently, to facilitate an interface with card services, 
OS/2 client drivers must be written as device dri- 
vers. 

Client drivers communicate with card services 
to manage specific types of PCMCIA cards (such 
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as flash cards) or even a specific implementation of 
a PCMCIA card (such as the IBM PCMCIA 
Data/Fax Modem). As the name implies, pro- 
grams register as clients of card services. During 
registration, a client indicates a set of events, such 
as card insertion and ejection, it is interested in 
monitoring. When an event occurs, card services 
notifies all clients registered for that event via the 
client’s callback handle. For example, inserting a 
card into the system generates an interrupt. Socket 
services fields the interrupt and informs card ser- 
vices of the activity. In turn, card services notifies 
each client registered for the card insertion event. 
The client callback routine determines that a card 
has been inserted into the system. From there, the 
client driver interrogates the card information 
structure (CIS), the content and organization of 
which is defined by the PCMCIA standard, to 
determine if it is the card or type of card the client 
driver is managing. 
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Card Information Structure. The CIS is a 
linked list of data structures called 
tuples. The information contained in a 
tuple is used not only to initialize the 
card but also to automate the opera- 
tions and configuration of associated 
applications. Figure 2 shows an 





Figure 2. PCMCIA card information structure 





Figure 3. [BM High-Speed Data/Fax Modem serial port 
identification function extension tuple. The value 17x is 
assigned by PCMCIA for the function extension tuple 
(CISTPL_FUNCE). 


overview of the CIS organization. 

A tuple cannot exceed 128 bytes in 
length; the first byte denotes its func- 
tion. The PCMCIA specification defines 


a set of tuple functions such as 
CISTPL_FUNCE, which details functional 
information about the card, The second 
byte, known as the tuple link (TPL_LINK), 
contains the number of bytes until the 
start of the next tuple in the CIS chain, 
thus linking one tuple to the next. 

For example, the IBM High-Speed 
Data/Fax Modem contains several 
CISTPL_FUNCE tuples. Figure 3 shows the 
serial port identification function exten- 
sion tuple, while Figure 4 shows the fax 
Class 2 function extension tuple. 
Although both of these tuples are CIST- 
PL_FUNCE types, Figure 3 details the 
UART capabilities while Figure 4 
details the fax Class 2 capabilities of the 
modem. Also note that the TPL_LINK field 
value varies between the two tuples. 
Figure 3 contains only four bytes of 
information after its TPL_LINK field, while 
the tuple in Figure 4 has seven bytes. 
Yet both are CISTPL_FUNCE tuple exam- 
ples. Together, these examples show 
the types of capabilities described in 
the CIS tuples. 


TYING IT ALL TOGETHER 

While the power of CIS information 
may not be readily obvious, consider 
how data or fax applications are 
installed, configured, and operated in 
today’s environment. 

Ideally, a PCMCIA data/fax appli- 
cation could perform several functions. 
It could be a card services client driver, 
functioning as both an application and 
a data/fax client driver. When the 
application is invoked, it would regis- 
ter with card services as a client inter- 
ested in the card insertion and ejection 
events. The application would, in this 
way, gain control and interrogate the 
card to find out whether it is a modem 
card and determine its capabilities. 

Instead of asking for information 
regarding COM port assignment, speed, 
and even fax capabilities during installa- 
tion, none of this information would be 
required to support a PCMCIA data/ fax 
modem, because that information 
resides on the modem’s CIS. The 
data/fax application could interrogate 
the CIS to make these determinations. 

To do this, the client driver would 


issue the card services GetConfigura- 
tionInfo() function to receive basic 
information (such as manufacturer 
identification) on the card. With this 
information, the client could determine 
if a modem were inserted. 

If a modem were indeed present, the 
first order of business would be to allo- 
cate unclaimed resources, such as a 
base address and an IRQ level, to it. 
Because data/fax applications general- 
ly expect a modem to be mapped to 
architected COM port resources such as 
COM2 (or a base address of 02F8x and 
IRO level 3), current modem client dri- 
vers resort to these same values to 
insure compatibility with these existing 
applications. This setup stifles the 
inherent power of PCMCIA. 

But if a data/fax application were 
to drive the PCMCIA modem as a 
client driver, card services could be 
allowed to assign any free address 
space and IRQ, rather than a specific 
one, because the application program 
could adjust to accommodate the new 
base address and IRQ values returned 
by card services. 

Additionally, by combining PCM- 
CIA client driver support into the 
data/fax application, there is no longer 
a need to query end users for informa- 
tion such as COM port assignments 
during the installation process. In other 
words, because the application is the 
client driver managing the PCMCIA 
modem, it will request the COM port 
assignment dynamically when the card 
is inserted into the system. 


WHAT'S IT ALL MEAN? 

With today's modems, COM port 
resources are statically reserved for a 
device regardless of whether the device 
is used during that session. With PCM- 
CIA and client drivers, resources can be 
acquired only when the associated 
device is present and any resources 
available when the card is inserted can 
be utilized. This is accomplished via 
the RequestIRQ() and RequestI0() func- 
tions. For example, a PCMCIA modem 
client driver could loop through the 
various IRQ levels until it successfully 
obtains one. 
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Once the data/fax application client 
driver acquired the necessary IRQ and 
I/O address space, it would then inter- 
rogate the card’s CIS further. To tra- 
verse the CIS, a client can use the Get- 
FirstTuple() and GetNextTuple() functions. 
These functions return the tuple func- 
tion (CISTPL_FUNCE) and link (TPL_LINK) 
fields, as shown in Figure 3. Alternate- 
ly, a client may advance directly to a 
particular tuple of interest. In the case 
of the PCMCIA High-Speed Data/Fax 
Modem, a client driver may wish to 
skip directly to the first CISTPL_FUNCE 
tuple to access the modem capabilities. 
To do so, a client would enter the CIST- 
PL_FUNCE value into the “DesiredTuple” 
field within the GetNextTuple() function. 
Once card services locates the tuple, the 
client driver would then issue the Get- 
TupleData() function to retrieve the infor- 
mation contained within that tuple. 

In the case of the PCMCIA data/fax 
modem, while processing these tuples 
the client driver would learn the speeds 
supported by the card (14.4 kbps for 
both data and fax) as well as its fax 
capabilities (Class 1 and Class 2). 
Because it could interrogate the card, 
an application would not need to poll 
the user during installation. Addition- 
ally, should the user choose to insert a 
different PCMCIA data/fax modem in 
the future, the application would not 
need to be reconfigured because it 
would dynamically adjust itself based 
on the capabilities of the modem as 
defined on the card's CIS. 

Another feature that could be incor- 
porated into a data/fax client driver is 
a prompt that would alert users to 
insert a card in the event that they 
attempt to transmit a fax or data while 
the card is absent from the system. 

Finally, when the user removes the 
modem from the system, socket ser- 
vices would field the interrupt and 
notify card services of the event. Card 
services would then notify each client 
driver that registered itself for the 
CARD_REMOVAL event. After determining it 
was the PCMCIA modem card that 
was ejected from the system, the 
modem client driver would then free 
the I/O address space and IRQ 









resources it had allocated to that card 
with the ReleaseI0() and ReleaseIRQ() 
functions. 

In the case of a PCMCIA modem, an 
existing data or fax application could 
be modified to incorporate the client 
driver functions. 
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“Hex Value Tuple Function Description 
17 CISTPL.FUNCE © Function Extension Tuple 
07 TPL_LINK Link to next tuple; here 7 bytes follow 
23 TPLFE_TYPE Fax description 
03 TPLFE_UF data rate 
00 
OF TPLFE_FM modulation: val, V27, V29 
00 TPLFE_FY data ion 
22 TPLFE_FS fax Feature polling TA 
00 TPLFE_CF country code not supported 


Figure 4. IBM High-Speed Data/Fax Modem Fax class 2 function extension tuple 


Dana L. Beatty, /BM Corp., 1000 NW 5ist 
St., Boca Raton, Fla. 33431. Beatty is a 
staff programmer in IBM's wireless data 
development department. She was the 
lead programmer on the IBM PCMCIA 


products to ship DOS and OS/2 PCMCIA 
client drivers. Currently the software team 
lead on the Cellular Digital Packet Data 
project, Beatty received her B.A. in com- 
puter science from the University of Texas, 
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In this issue we introduce a new section, “The Advanced Novice,” for programmers just beginning to explore the 
world of OS/2. This article deals with a concept basic to object oriented programming—reusable code and 
reuse techniques. BY JOSEPH H. MCINTYRE 


Reuse: Recognizing 
The Opportunities 


or many years, the job definition of a sys- 

tems analyst was identified with the term 

“efficiency expert” and the elimination of 
redundant manual processes. The work involved 
determining current processes, their products, 
and the factors surrounding and affecting, or 
being affected by, each process. With the collec- 
tive knowledge about the processes, an analyst 
could create alternative methods, either by apply- 
ing new models or replacing the current model 
with a known better model. The selected alterna- 


Knowleage is fundamentally 
reusable; collecting and distributing 
that knowledge Is the challenge. 


tive model could then be monitored and evaluat- 
ed; if successful, it could be applied elsewhere. 
The efficiencies from each successful model built 
on previous models and became foundations for 
the next. 


REUSE IS NOT NEW 

Reuse is a cornerstone of the analyst's task. 
Improving processes through the elimination of 
redundancies can be the easiest route to identify- 
ing, assessing, quantifying cost savings, and 
implementing new systems. Application of suc- 


cessful models to new processes reduces time to 
enact and lessens the chance of repeating short- 
falls of previous implementations. The concept of 
reuse, of course, may also be applied to the work 
of the analyst. 


SOME EXAMPLES 
In software development today, many people con- 
sider reuse to encompass only code libraries and 
object-oriented programming technologies. This is, 
however, a narrow and restrictive view. 

Knowledge is fundamentally reusable; collect- 
ing and distributing that knowledge is the chal- 
lenge. Tips and Techniques documents can be col- 
lected from many users’ experiences. The result- 
ing information may be combined and released as 
a book or on-line reference, or placed in a reposi- 
tory. Users can use it to record or build detailed 
information suitable for their environments. 

Operating system API calls are designed to be 
applicable to many applications, making it prefer- 
able to utilize the API instead of writing new sub- 
systems specific to an application. For instance, in 
OS/2 the window management APIs are used by 
graphical programs. While these APIs may be 
extended by an individual application where 
desired, they would never be entirely replaced. 
Because PM's extensible architecture offers stan- 
dard methods for implementing extensions (for 
example, subclassing and DLLs), working with 
extensions is relatively straightforward. 

Test cases for an application may be run on 
multiple workstations with differing configura- 
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tions by including setup variables or environment 
settings for variables such as hardware installed, 
network names, and connections. This allows test 
plans and test cases to be moved to a different 
environment, used in subsequent releases, or used 
to test companion products. 


REUSE THROUGHOUT THE 

DEVELOPMENT CYCLE 

If reuse—and the processes for developing 
reusable deliverables—is applied to all phases of 
the software development process, there are many 
opportunities for improvements. Each phase holds 
different opportunities, but deliverable candidates 
for reuse are best identified and prepared before 
they are produced. This leads to design with mini- 
mal restrictions on reuse. 

In the analysis phase, reuse can eliminate repet- 
itive work. Searches for past models, data dictio- 
naries, new business models, and concurrent pro- 
jects may yield knowledge applicable to a current 
project. Other projects can be enhanced by saving 
even the information not directly used on a project 
(it is also wise to retain information in case the 
analysis is later reviewed). 

Applying reuse to architecture-level designs 
can yield design documents that can be applied 
across platforms or projects much more readily 
than code derived from them. It is also easier to 
expand or limit concepts at the design stage. The 
important distinction between design and code is 
that code is a single implementation of a design. In 
many cases, design documentation is much more 
useful to a subsequent user than is the source code 
itself. (At a minimum, the code can be used as a 
reference.) An excellent example of this is the con- 
trast between the API reference and Programming 
Guides from the OS/2 toolkit. It would be very 
difficult to program for Presentation Manager 
using only the API reference without the concepts 
presented in the Guide. 

In the coding phase, suitability for reuse is 
determined by a number of factors including the 
tools used, the physical state of the code (how 
modular, whether there are global variables, nam- 
ing conventions, and so on), and the quality of the 
code (in the context of both the original application 
and other possible applications). The following 
sections give some guidelines. 
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Compiler Languages. It is best to consider your reuse 
goals before determining the language you will 
use to pursue them. There are several pitfalls to 
watch for. 

If you work in a mixed-language environment 
(this includes a single language used on multiple 
platforms), it is important to anticipate translation 
and connection hurdles. Assembler is not easy to 
read or understand; libraries may be limited to a 
specific platform or compiler and some languages 
cannot call subroutines written in other languages. 
An emerging technology is the language-indepen- 
dent System Object Model (SOM), which allows 
the creation of bindings that let applications and 
objects written in different languages communi- 
cate transparently. 


In many cases, design 
documentation is much more 
useful to a subsequent user than 
is the source code Itself. 


Modularity is very important. It is desirable to 
have the smallest meaningful component that can 
be utilized with minimal effort. This may refer to 
anything from a single function to a complete sub- 
system. For example, CenterWindow is a single 
function reusable component that positions a win- 
dow in the center of another window. At the other 
extreme, Lotus 123 for OS/2 and Freelance Graph- 
ics for OS/2 share the same graph engine. In both 
of these examples, the reusable component pro- 
vides a well defined, concise function to the appli- 
cation it serves. 

If a product will be extensible by a customer, 
consideration of the customer is important. In 
some cases, source code is required, which may 
not be acceptable for the vendor. 

Source code (not just comments) must be read- 
able and logically organized. Well-structured code 
has meaningful variable names, related functions 
grouped logically, and well-organized modules if 
a task involves code in more than one source file. 
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Table 1. A simple knowledge repository 


Table 2. Reusable components for a phone number 


Coding conventions such as module 
file names, file header comments, and 
code formats make navigation and 
reading easier. 


Testing. In the testing phase, reuse may 
include maintaining test cases across 


product releases, sharing test cases 
between products (for example, using 
the same services of the operating sys- 
tem) and bringing unit-test cases for- 
ward from programmers to testers. In 
both automated and manual environ- 
ments, a well designed test case suite 


can provide a good reuse foundation 
with little additional effort. 

Many test cases are exactly the same 
except for one or two steps; the first 
reuse candidate is therefore the test 
cases themselves. Creating a test case 
should start with foundation cases and 
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be filled out with specific cases that 
address differences. A foundation test 
case may not be a full case; instead it 
may provide environment information 
and application setup on which other 
cases will build. Future test cases may 
be built by extending this foundation 
case, rather than using a more compli- 
cated existing case and removing 
unnecessary steps. 

Most test cases would run identical- 
ly on all machines—except for a few 
machine-specific variables like the net- 
work name for the workstation or a 
server name. Test cases should not 
include hard-coded names; instead, 
they should use aliases, variables (in 
the case of automated tools), or general 
names (for manual cases). These allow 
names to be configured for individual 
workstations. 

Often, while a test case is running, 
a new error is found for which a test 
case does not exist. A new case, based 
on the current one, should be created 
to ensure that the condition will be 
tested. If a framework exists, genera- 
tion of the new case is easy; the foun- 
dation case for the current test case 
can be extended to test the new condi- 
tion. 


Installation and Maintenance. The deliv- 
ery and maintenance phases have a dis- 
tinctive reuse opportunity, namely the 
installation and service programs. 
Install programs all do the same thing, 
more or less—copy files, set up the user 
environment for the application, possi- 
bly do initial program setup to cus- 
tomize applications for the user. Ser- 
vice programs check service levels and 
replace files; they may provide other 
services like rollback of changes. 

There are many installation pro- 
grams, ranging from simple batch pro- 
grams to full graphical interface appli- 
cations. Applications that come with- 
out an install program are natural 
candidates for reuse. 

If you don’t have a solid install 
base on which to build, products that 
provide this foundation can be a good 
starting point for creating custom 


install and service programs. These 
include the Stirling Group’s Install 
Shield and IBM’s Software Installer 
for OS/2. 


THE FOUNDATION FOR REUSE 
The foundation for effective reuse is - 
documentation. Specifically, the entire 
software cycle for a component must be 
available in complete, accurate, and 
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Table 3. Changes to reflect a possible area code change scenario 


sufficient documents. This allows you 
to determine the applicability of a com- 
ponent to another project with no prior 
knowledge of that component. Ideally 
(and to be effective in large systems), 


these documents should be in a form 
suitable for retrieval in an interactive 
browsing environment. 

Absent of an electronic environment 
providing advanced search capabilities 
within the context of components, there 
are many other effective storage and 
retrieval techniques. The most basic is a 
collection of facts in a knowledge base, 
which can range in scope from a primer 
on a business process to an encyclope- 
dia in a CASE tool. From this set of 
facts, viewers can retrieve information 
from the data. For a text file, many 
tools can provide search and hyperlink 
capabilities; the data in a CASE tool 
encyclopedia can be displayed as dia- 


grams or forms. Even paper in a cen- 
tral filing cabinet is a start. The impor- 
tant point is that there is a common 
repository (or repositories) that people 
know how to access. A simple reposito- 


The foundation for effective reuse 1s documen- 
tation. Specifically, the entire software cycle 
for a component must be available in complete, 
accurate, and sufficient documents. 


ry is described in Table 1. 

A component always contains a con- 
cept; it may also contain any number of 
stages through one or more implemen- 
tations. Following are some examples 
of different components. 


Phone number. 

* Concept—an explanation of the 
valid phone number sequences for 
all numbers around the world, 
include information such as the for- 
mat expected by each country. 

* Design—a logical data type descrip- 
tion to implement phone number 
data structures. Validation informa- 
tion such as country codes could 


also be documented. 

* Coding—Cobol copy book, C data 
structure, C++ class object model, 
and object class implementation. 


Using a Dynamic Data Exchange (DDE) 

server in an OS/2 program. 

* Concept—explanation of DDE ser- 
vices and where to use them; com- 
parison to other alternatives. 

* Design—implementation alterna- 
tives for creating DDE clients. 

* Samples—sample implementations, 
possibly in pseudo-code. 

* Coding—code fragments, working 
samples. 

In both these cases, the documents are 

easily extensible. In fact, the phone 

number could apply only to North 

American numbers, then be extended 

to included worldwide numbers. Note 

that in the phone number example 
actual code implementations were pro- 
vided, whereas in the DDE example 
samples were provided. With DDE, the 
subject is very dependent on its appli- 
cation; thus a generic solution is not 
likely to be useful. Templates are pro- 
vided, however, as a starting point. 
The important point is the availabil- 
ity of knowledge on a subject, not just 
the final implementation; not only the 
code can be reused; so can all the work 
that provided the knowledge on which 
the code was based. This has some 
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obvious advantages: 

¢ Collaborative work by experts. Each 
expert can provide specific knowl- 
edge, allowing those in other areas 
to expand the work. 

¢ Revisions can be documented 
throughout the entire component, 
applied at the level on which the 
change is most appropriate, and cas- 
caded through the other levels. 

e The structure for the documentation 
allows different people to work 
within a framework. 

¢ The structure helps people think in 
terms of components rather than 
whole solutions. 

This concept seems at first to introduce 

a lot of work. Much of this work, how- 

ever, is being done but is unrecorded. 

Top down, bottom up, and object-ori- 

ented design all break problems into 

smaller units. Reuse helps when units 
are discovered, during searches for an 

existing component that satisfies a 

need, or when creating a new reusable 

component. 

Tables 2 and 3 show the before and 
after images of two repository docu- 
ments for U.S. phone numbers. There 
is little work required to maintain the 
documents. 

Information on reuse can parallel 
that on object-oriented techniques. 
Reuse, however, extends beyond 
object-oriented work; the concepts 
apply to existing processes as well. 
Object-oriented environments do pro- 
vide additional facilities to implement 
reuse more effectively. 

A search for an existing component 
can be executed in one of several 
ways, depending on the component 
and the context of the need. For 
instance, the phone number search 
could consist of a search in a CASE 
tool repository and information from 
programmers or a long distance phone 
company. Searches vary depending on 
available information and additional 
requirements. 

Collected information should be 
stored in a repository (a CASE tool, a 
repository product, or even a text file 
in a known place) that makes the infor- 





Figure 1. Good reuse implementation (continued on page 90) 
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mation available for future use. This 
makes information more stable as 
knowledgeable people move and the 
knowledge they have acquired moves 
with them. 


AN EXAMPLE OF REUSABLE CODE 
Figure 1 shows a set of file fragments 
that demonstrate the separation of user 
interface code from application logic 
code in an object-oriented language. 
The example uses SOM, although the 
principles can be applied to other lan- 
guages that support inheritance. 

The application object is defined, 
followed by an object that inherits 
from it and adds the user interface 
functionality. The object user can 
decide whether to use the application 
object independently or with the user 
interface code. This setup also pro- 
vides multiple user interface imple- 
mentations for the single application 
object. 


REUSE ISSUES 

This section is intended to provoke fur- 
ther thought on the applicability and 
benefits of reuse techniques. Try to 
envision these issues in the context of 
your environment. 

Reuse is the responsibility of the 
provider, not of the user. The provider 
contributes the knowledge and imple- 
mentations to the repository. The user, 
on the other hand, simply selects com- 
ponents from the repository for inte- 
gration into other products. If a com- 
ponent is not suitable, the user will not 
use it. It is therefore incumbent on the 
provider to provide components suit- 
able for use, given an arbitrary and 
demanding user. 

Components must be able to be 
pulled cleanly from their existing 
product and incorporated without 
disturbing the environment of the 
new product. Otherwise, the process 
becomes too difficult and leads to 
rework. An example of a good reuse 
component is an independent module 
that contains financial calculations for 
mortgages. 

If a component relies on one or 


/* DialogProfileUpdate is the dialog window callback function for 
the update of the UserProfile object. */ 


MRESULT EXPENTRY DialogProfileUpdate (HWND hwnd, unsigned msg, 
MPARAM mp1, MPARAM mp2) 


{ 
static vWserProfile userprofile; 


switch (msg) 
{ 


case WM_INITDLG: 
/* get object passed in +*/ 


userprofile = (vUserProfile) mp2; 


File: MAIN.C 
vUserProfile userprofile; 
Environment *ev; 


/* create new object */ 
ev = somGetGlobalEnvironment (); 


userprofile = vUserProfileNew (); 


/* set values for object attributes +/ 


/* display update dialog */ 


-UpdateProfile (userprofile, ev, HWND_DESKTOP, HWND_DESKTOP); 


/* release object */ 
_somFree (userprofile) ; 


Figure 1. Good reuse implementation (continued from page 88) 


more other components, the interfaces 
should be clearly defined such that the 
dependencies can be replaced with 
functional equivalents. Dependencies 
should be documented so the depen- 
dent components’ interactions with 
their dependencies need not be 
known. 

Documentation should be complete, 
accurate, and sufficient. The benefit of 


reuse is not realized if the user must do 
as much work using the component as 
writing a new one. All documentation 
should be maintained with the compo- 
nent; changes cannot be made at one 
level without updating the appropriate 
information in the other levels. The 
update in other levels may implement 
the changes or indicate the level to 
which the component complies if it 
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does not fully implement the changes. 
For instance, the design document for 
phone numbers could include country 
code, but the Cobol copybook may not 
implement international numbers. This 
would be stated in the Cobol copybook 
documentation. 

Reuse requires thought. It also 
requires vision to recognize some less 
obvious opportunities for reuse. Reuse 
can also inspire better solutions, 
adding a context in which picturing a 
component acts as a catalyst for new 
ideas. 

Applying reuse concepts does not 
require a new set of tools; these con- 
cepts can be applied to existing frame- 
works and extended to fit the require- 
ments of your environment. Practical- 
ly, enabling tools are necessary to 
facilitate searches through a large num- 
ber of components and provide reposi- 
tory services. But even if the concepts 
are applied only to individual work, 
they can provide insight into the func- 
tion and benefit of the techniques. 
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1. Keep Your Trash Out of the Gutter: Sweep 


2. Get Rid of Garden Pests: Put ladybugs or 


5 temative ideas to herbicides and pesticides 
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CONCLUSION 

Reuse is often taken for granted. A goal 
of many development methodologies, 
it is being incorporated in a number of 
ways. Understanding the concepts and 
deliverables of a system in which reuse 
is utilized provides a clear vision of the 
environment and possible benefits. 


Water is not the pure and natural resource it once was. The effects of global warming, acid rain, 
and chemical technology have tampered with it. To protect our water from pollution, we ask that you 
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think about how you dispose of chemicals, garbage, and other contaminants. 


your driveways and sidewalks instead of hosing 
them with water. Put trash in the can instead 
of the gutter. 






praying mantis in your garden instead of using 
insecticides, Contact your local nursery for al- 
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&. Fix Your Car Leaks: Recycle your motor oil 


at your local mechanic or garage. Don’t dump 
it into a storm drain. More oil enters beaches 
and lakes from urban runoff than from tanker 
spills, 
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his article introduces the concepts of XMP 

and XOM, which represent the primary 

programming interface for LAN NetView. 
It covers building and analyzing the data struc- 
tures associated with XMP/XOM and construct- 
ing simple management requests to agents devel- 
oped for LAN NetView. In an upcoming article, 
we will unite these programming concepts with 
the actual agent implementations and framework 
facilities provided by the LAN NetView Man- 
age/Enabler products. 

As described in the first article of this series 
(“LAN NetView: A Programming Overview,” 
OS/2 Developer, July / August 1993), LAN NetView 
is a platform or framework for the development 
and execution of applications used to manage net- 
work resources, It should not be confused with 
network managers, as it can manage a system 
rather than just a network. “System” here refers to 
applications and physical resources that can be 
addressed with Agents supplied or written by var- 
ious resource owners. Examples of resources 
include IBM’s Database Manager, Communica- 
tions Manager/2, OS/2 2.0 and 2.1 products, 
router hubs, adapter cards, and so on. As an anal- 
ogy, LAN NetView can be considered an operat- 
ing system for management applications. It per- 
forms or provides many of the services common to 
all management applications, including memory 
management, transport services, request dispatch- 
ing, and information routing. 

There are currently three major protocols that 
define management interfaces, Simple Network 


Management Protocol (SNMP), Common Manage- 
ment Interface Protocol (CMIP), and SNMP 2. 
While the relative merits of each protocol are 
beyond the scope of this article; the subject has 
been covered extensively. At a high level, CMIP 
provides much more robust functionality than 
SNMP, but not without significant overhead in the 
implementing software and increased complexity 
in the specification of the operations to be per- 
formed. Today, although CMIP is gaining popu- 
larity, the vast majority of applications are written 
to the SNMP specification, and LAN NetView pro- 
vides support for both. Where not otherwise indi- 
cated, this article focuses on programming to the 
CMIP specifications. 

A final topic before getting into coding specifics 
is the transport of data between managing and 
managed nodes. By its very nature, SNMP uses 
TCP/IP to flow information between nodes. 
CMIP, unhampered by this restriction, has both 
CMOT (CMIP over TCP/IP) and CMOL (CMIP 
over Logical Link Control, or LLC). Within the 
LAN NetView framework, it is not vital that a 
developer understand the underlying transport to 
develop effective applications. All software writ- 
ten to function using the CMIP structures will 
operate transparently in both the CMOL and 
CMOT environments. LAN NetView’s supporting 
APIs are not concerned primarily with the trans- 
port mechanism. APIs for SNMP and CMIP are 
similar and, as mentioned above, little or no dif- 
ference exists between CMOL and CMOT with 
respect to application development. 
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PROGRAM DESIGN CHARACTERISTICS 

The LAN NetView products implement the 
X/Open Management Protocol (XMP) and 
X/Open Abstract Data Manipulation (XOM) API 
specifications and its implementation adheres 
closely to the X/Open specifications. Although 
there are a few minor differences, they typically 
have little or no impact on the developer, repre- 
senting a proper subset of the allowed function 
defined by the X/Open specifications. This feature 
is important since it assures some measure of 
portability with other platforms claiming support 
for XMP and XOM APIs. 

At a block diagram level, programs using the 
XMP/XOM API calls have a similar structure. The 
program is divided into four segments: object or 
data definition, initialization, operational, and ter- 
mination. 

Addressing application development, we begin 
with the initialization and operational stages of 
defining the application. These, in turn, require the 
use of data structures that form the core of the 
application’s definition segment. This article is 
intended as an introduction to building the 
required data structures, issuing management 
requests, and interpreting the results. The LAN 
NetView Developer's Reference Manual and LAN 
NetView Administrator's Guide provide more com- 
prehensive detail on the framework and program- 
ming structures. A set of samples are also provid- 
ed with the product. 


XMP 

The XMP/XOM API set is shown in Figure 1, 
which consists of collections of management verbs, 
administrative functions, and data manipulation 
functions. The protocol functions of XMP are bro- 
ken down to request functions and the corre- 
sponding response functions. The ability to man- 
date a confirmation or response is a configurable 
characteristic of the XMP API. These functions 
consist of the prefix mp_, the function name, and a 
suffix of either _req or _rsp. For example, the GET 
function is coded as mp_get_req() and the response 
mp_get_rsp(). 

The administrative functions, which also have a 
mp_ prefix, are used to initialize or terminate an 
application within the NetView platform. All data 
constants and macros are written in capitals, while 
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all functions are lowercase. In the following exam- 
ples, the macros and functions that contain the 
prefixes om_ or 0M_ are XOM functions macros and 
data constants used for the definition, manipula- 
tion, or deletion of data within defined data struc- 
tures. 

The general structure of a LAN NetView appli- 
cation (not including the data definition aspects) is 
shown in Figure 2. At a minimum, all LAN 
NetView programs must contain mp_initialize, 
mp_version, and mp_bind function calls. These three 
functions establish a connection to the platform 
from within an application. The function mp_ini- 
tialize is called first to define a workspace or data 
area, which holds the data structures that XMP 
and XOM require to operate properly. The second 
function, mp_version, defines characteristics of the 
interface and provides for loading of common rou- 
tines used to process data within the application. 
Finally, mp_bind establishes the pathway to the 
framework that generates and returns responses 
to management requests. 


All LAN NetView programs must 
contain mp_initialize, mp_version, 
and mp_bind function calls, which 
establish a connection to the 
platform from within an application. 


Since OS/2 is a multithreaded environment, it 
is possible to have multiple mp_bind functions for a 
single initialization request. This function is useful 
when management requests are responded to 
infrequently. For example, a request may report 
when a security or access violation occurs. Since 
these events are rare, a separate thread can be 
spawned for each resource for which security 
must be tracked, with each thread accomplishing 
totally different management functions and hav- 
ing its own mp_bind and specific management 
request. Although there is a limit of 30 mp_bind 
functions per mp_initialize, multiple workspaces 
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Figure 1. XMP functions to support CMIS and SNMP services 
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can be defined with multiple calls to 
the mp_initialize function. This applica- 
tion is diagrammed in Figure 3. 

The previous discussion centers on 
the fact that XMP/XOM uses synchro- 
nous calls as its default mode.With syn- 
chronous calls, a thread or process 
blocks or waits until the function exe- 
cution completes; whereas if an access 
violation never occurs, each thread 
waiting for an occurrence is blocked 
indefinitely. The platform also allows 
for asynchronous operation, in which 
control continues when a request is 
made. When the operation completes, 
the requesting application is signalled 
and the resulting data can be 
processed. In the previous example, a 
single thread or process using a single 
mp_bind could issue multiple requests 
asynchronously for access violation 
data, as shown in Figure 3. 

Once a bind is completed, it is possi- 
ble to issue a management request. For 
CMIP, possible requests include 
mp_get_req, mp_set_req, mp_action_req, 
mp_create_req, mp_event_report_req, 
mp_delete_req, or mp_cancel_get_req. Each 
function has a similar parameter set, 
hence the notion that these represent a 
single API of the form mp_xxx_req() or 
mp_xxx_rsp() (see Figure 4). This article 
focuses on the mp_set_req function. 

For SNMP, only four functions are 
used: mp_get_req, mp_set_req, mp_get_next_req, 
and mp_event_report_req. The mp_get will be 
described in a later article; its relation- 
ship to the other functions can be 
inferred with little difficulty. 


PARAMETERS 

At this point we are ready to write our 
first application segment, shown in Fig- 
ure 5. Notice that the result of each API 
call is a status; this is important because 
only when the status indicates success 
is a valid result guaranteed. The result 
of each API call must be checked for a 
successful return before proceeding to 
the next function call. 

While it shows structure, Figure 5 
does not identify the parameters associ- 
ated with each call. The definition of 
the parameters leads to the data defini- 





workspace=mp_initialize ( ); 
feature_list [0] = MP_CMIS_PACKAGE; 
status=mp_version (workspace, feature list)); 
if (status I = MP_STATUS) { 

printf {" mp_version error" \n); 

(void) om_delete (status); 

return (-1); 





} 


status=mp_bind)MP_DEFAULT_SESSION, workspace, &session) ; 
if (status '= MP_STATUS) { 

printf {" mp_bind error" \n); 

(void) om_delete (status); 

return (-1); 


} 
status=mp_set_req) MP_DEFAULT_SESSION, MP_DEFAULT_CONTEXT, 
argument, &result, &invoke_id); 


i] 


mp_unbind (session) 
om_delete (session) 
mp_shutdown (workspace) 


Figure 2. Simplified structure of LAN NetView application 





We'd like to say a word about 
client/server development. 


TESTING. 


You've chosen the platform, architecture, 
development tools, and application. Now's 
the time to decide how you're going to test 
your client/server applications. 


The Softbridge Automated Test Facility (ATF) 
lets you fully automate regression testing, 
letting you test "often and early" in the 
development cycle. And that means lower 
costs, decreased time to release, and higher 
quality results. 


If you're building client/server (or stand- 
alone) applications under OS/2, Windows, 
or NT, you should be using ATF to test them. 
To learn more about ATF, call 800-955-9190. 


ATF. The final 


word in testing. 


_-] Softbridge, Inc. 
617-576-2257 (Phone) 
617-864-7747 (FAX) 





tion aspects of programming to the 
framework and into the utilization of 
XOM functions (used in manipulation 
and creation of the complex data struc- 
tures used by the LAN NetView plat- 
form). As most developers discover, 
while the operational coding is very 
simple, the definition of parameters in 
the operational statements and the 
results of a management request tend 
to be rather complex. 


OBJECTS 

XMP and XOM rely on a definitional 
notation that specifically and unam- 
biguously defines a piece of informa- 
tion. Within the X/Open specifica- 
tions, these are referred to as objects. 
Objects are arrays of triplets called 
descriptors. The first descriptor in the 
array is a header and the last consists 
of nulls, as in Figure 6. The standard 
programatic representation is shown 
in Figure 7. 

Each descriptor consists of a type 
syntax and a value. The type field iden- 
tifies the descriptor, while syntax identi- 
fies the type of data represented by the 
descriptor and value contains either the 
data or a pointer to the data. For exam- 
ple, a descriptor may depict: 


memory_size,integer, 300 


Here the type is memory_size, its syn- 
tax is integer, and the value is 300. 
Descriptors can be more complex; the 
syntax field can describe a string or an 
object type (a pointer to an array of 
descriptors). For example, memory size 
can be represented in bytes, pages, or 
kilobytes. The descriptor definition 
might then have the structure shown in 
Figure 8. Structures can become very 
complex, with multiple levels of nest- 
ed object definitions. 


PACKAGES 

To begin coding, a developer must 
define the “packages” used by the 
application. Each package is a collec- 
tion of data structures defined for use 
with an associated agent or agents and 
represented by all or part of a DLL. 


SYNCHRONOUS OPERATION 


PROCESS 


THREAD 1 


MP_GET_REQ() 


THREAD 2 


MP_ACTION_REQ() 


THREAD N 


MP_SET REQ() 


ASYNCHRONOUS OPERATION 


PROCESS 


MP GET REQ() 


MP_ACTION_REQ() 


MP_SET_REQ() 





Figure 3. Multiple workspaces defined with multiple calls to the mp_initialize function 
a 


C-API Function (XMP API) 
MP_status ms_xxx_req( 
OM_private_ob ject session, 
OM_private_ob ject context, 
OM_ob ject argument, 
OM_private_ob ject *result_return 
OM_sint *invoke_id_return); 
MP_status Success or an error object 
Session Management service characteristic 
Context Call specific characteristic 
Argument Function and View Specific Object 
Result Return-Function Dependent 


Invoke-Id-Return ID for Asynchronous Calls 
Figure 4. CM-API function (XMP API) 


Packages are identified in an object of 
type mp_feature, which is usually stati- 
cally defined. A sample feature list def- 
inition is given in Figure 9, section G. 
The feature list is used in the mp_version 
statement; the result of the mp_version 


function call can be used to check 
which DLLs are loaded. Unless space 
is at a premium, it is easiest to include 
all available packages in the feature list 
definition and reuse the code in each 
application. 


Sess BEF EL Or ER 





Figure 5. Application segment structure 


DESCRIPTOR, 


DESCRIPTOR, 


DESCRIPTOR, 








Figure 6. Array structure 





Figure 7. Standard programatic representation of array structure 


Figure 8. Descriptor with syntax field describing memory size 
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PROGRAM INITIALIZATION 

The mp_initialize, mp_version, and 
mp_bind functions are used to establish 
a connection to the framework. mp_ini- 
tialize returns a handle to a data area 
used by successive functions, while 
mp_version identifies the packages used 
by the application. The general form 
of the function call is 





mp_version(feature_list,ws) ; 


As noted earlier, feature_list 
describes the packages to be loaded for 
application processing. Packages are 
collections of definitional structures 
that describe the data represented in 
the application. They are necessary to 
handle differences between platforms 
for representation of string and numer- 
ic information. For simplicity, use the 
feature list definition given in Figure 9, 
section G. The vs parameter is returned 
from the mp_initialize() function. 

The final initialization function is 
mp_bind. Its syntax is 


mp_bind(session,ws,&bound_session) ; 


re 
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The session parameter defines how 
a connection is made. A pointer to a 
data area for the session is returned for 
this function; a context must then be 
defined for execution of the operational 
mp_xxx_req functions. Fortunately, 
default contexts and default sessions 
exist. (For this article, explicit session 
and contexts will be defined.) The 
defaults assume confirmed synchro- 
nous calls, with a response required for 
each request. The session object pro- 
vides for caller identification, which is 
necessary for a response. 

To build the CONTEXT and SESSION 
objects, two XOM functions, om_create 
and om_put, must be introduced. (Note 
that all XOM functions have the prefix 
om_. XOM functions deal solely with the 
definition and modification of data 
structures, whereas XMP provides for 
the creation and reporting of data or 
operations, based on the contents of 
data structures.) The first step is to 
build a shell of the structure of interest 
using om_create, which allows the defin- 
ition of an object of the class specified 
as a parameter. To define an instance 
of the CONTEXT object, exercise the func- 
tion call: 


_create(MP_C_CONTEXT,OM_TRUE,ws,&con- 
text); 


This builds an empty context object 
pointed to by &context. The second func- 
tion, om_put, allows us to complete the 
fields in the already-created context 
object. Its syntax is: 


om_put(context,0M_REPLACE_ALL, con- 
text_opts,0,0,0); 


om_put copies descriptors from the “pub- 
lic” object context_opts into the “private” 
context object. These public-to-private 
conversions must be performed on 
many objects used in the framework. 
Public versions of the objects can be 
modified directly, which is why they 
are created; however, private versions 
of the objects are most efficiently used 
by the platform. The variable 
context_opts can be defined as an object 





Figure 9. Sample feature list definition (continued on page 99) 
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Figure 9. Sample feature list definition (continued from page 98) 
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that contains context variable defini- 
tions to be changed from the default 
state. Similarly, the session object must 
be created using om_create and om_put 
functions. 

The next function is mp_set_req. Its 
general syntax is: 


mp_set_req(bound_session, context, 
argument, &result ,&invoke_id); 


In the parameter list, the last two para- 
meters define the result. For a synchro- 
nous case (defined in the context 
object), the answer or result of the func- 
tion call is returned in the result vari- 
able. For an asynchronous case, a tag or 
identifying integer is returned in the 
invoke_id and the result parameter is 
meaningless. (It is the developer's 
responsibility to keep track of the 
invoke_ids after each asynchronous 
function call; this will be covered in a 
later article on programming for the 
LAN Netview platform.) The first two 
parameters, bound_session and context, 
are obtained from the mp_bind and the 
om_put respectively. The last argument 
parameter is a complex data structure 
describing the data to be modified. 

The argument form is described as a 
CMIS Set Argument with the following 
definition, obtained from the X/Open 
XMP specification for the CMIS Set 
Argument. (Only the required descrip- 
tors are shown): 


base managed object class 
base managed object instance 
modification_list 


Each descriptor has a syntax of 
object, which implies some level of 
nesting. While it is possible to construct 
the argument dynamically, it is given 
in Figure 9, Section F, as a static “pub- 
lic” definition, which will then be 
copied into a private definition with 
om_create and om_put. 

We are now faced with defining the 
objects bmoc, bmoi, and mod_list. The low- 
ercase text indicates developer-chosen 

Notice that the definition of base 








] managed object class (bmoc object) is 


complete, in that a data value of type 
string has been assigned. (Within a real 
application a “real” class identifier 
would have to be selected. These class- 
es, defined in the LAN NetView Man- 
aged Object Catalogues, describe classes 
such as the operating system and the 
machine.) We can now proceed to the 
nested object bmoc. Because of the nest- 
ing, it is necessary to define the objects 
ds_dn, ds_rdn, AVA, and network_id. This 
procedure is shown in Figure 9, Sec- 
tions C and D. 

The definition of the base managed 
object instance is now complete. The 
data used in the instance descriptor is 
obtained from the specification of an 


specifications its structure is defined as: 
attribute_id 

attribute_value 

modify_operator_value\ 


The only object not completely 
described is the attribute id for the item 
to be modified. (It is important to note 
that all attributes are represented by an 
attribute id. For example, the buffer 
variable is actually identified by an 
attribute id of the form 1.3.66.77.62.2.) 

At this point, we have described the 
definition of a public object for a set 
argument; the code definition can be 
reused for all applications that need a 
set argument. Data portions can be 
modified using simple C notation. For 


In general, an argument structure must be 
defined only once. Once you have a set of 
these for each mp_xxx_reg function, they 
can be easily reused. 
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instance of an object at LAN NetView 
installation. (Only a portion of the 
instance is given in the previous fig- 
ures; a complete version can be found 
in the CompuServe OS2DF2 forum, 
library 13, under the name XMPDE- 
MO.C.) Our next article will give a 
more thorough description of the rela- 
tionship between object instances and 
LAN NetView. The actual structural 
specification of the objects and 
sub_objects is found in the X/Open 
book under “base managed object 
instance.” Everywhere an object is 
specified as a syntax, an additional 
level of definition must be accom- 
plished. Notice the relationship in the 
class name header and structure defin- 
ition. For example, an AVA object's class 
is MP_C_AVA. (The descriptors comprising 
the class are again found in the 
X/Open book under the class name.) 
The last structure to be defined is 
the modification list. In the X/Open 


example, to dynamically change the 
attribute value to 30, the C code 
mod_list 2 .value.integer=30; could be 
used. 

In general, an argument structure 
must be defined only once. Once you 
have a set of these for each mp_xxx_req 
function, they can be easily reused. 

At this point, we can show the struc- 
tures associated with the CONTEXT and 
SESSION objects. Recall that we needed to 
define some data so the om_put could 
place these values in the objects. 

For SESSION, we need to include a title 
sO a response can be routed back when 
a request is made. For context, we will 
specify confirmed mode and request 
that the result be returned synchro- 
nously. These can be seen as the 
req_title, session_opts, and context_opts 
definitions in Figure 9, Section A. 

Once the static structures are 
defined the code is relatively complete; 
it is time to build the argument and 


issue the set request. The complete 
code appears in the CompuServe 
OS2DF2 forum, library 13, under the 
name XMPDEMO.C. 

Creating the private version of the 
set argument is optional. Doing so, 
however, can simplify memory man- 
agement and improve performance. 

At this point, all coding necessary 
for the execution of set has been com- 
pleted. A complete code segment can 
be found in XMPDEMO.C, shipped as 
a sample with the LAN NetView Man- 
age product. 


HOUSEKEEPING 

One of the more troublesome portions 
of the framework, and of the X/open 
API in general, is that the function calls 
allocate space and return pointers to 
that space. This is true for results 
returned from the mp_xxx_yyy() API and 
the om_create and om_get function calls 
from XOM. Failing to delete structures 
no longer in use can lead to uncon- 
trolled growth in the memory neces- 
sary to run an application and eventu- 
ally cause a swapper.dat full error. It is 
easy to delete unnecessary structures 
with the om_delete() function: 


om_delete(result) ; 
om_delete(arg) ; 


The only caveat is that deleting a 
nonexistent entity can cause an abnor- 
mal exit from the program. On the 
other hand, if unused data is not delet- 
ed, an application will require more 
and more space to continue execution. 
Asa rule, make sure that all public and 
private objects are deleted once they 
are no longer in use. Because each new 
call to an XOM/XMP function results 
in a new area being allocated, there is 
no advantage to keeping unused struc- 
tures around, 
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New Tools, Applications, 


And Support 


TOOLS 


CICS Wrapper for PARTS Workbench. A 
J component for the PARTS Workbench, 
aay s CICS Wrapper allows developers to 
connect PARTS applications to on-line transaction 
processing power. PARTS is a client/server inte- 
gration toolset that enables visual application con- 
struction from prefabricated software components. 
Developers can use the CICS Wrapper to access 
mainframe transactions and data. 





Digitalk Inc. 
Phone: (310) 645-1082 Fax: (310) 645-1306 


DeskMan/2. DeskMan/2 manages the OS/2 Work- 
place Shell, selectively saving, restoring, and 
migrating WPS objects, controlling object styles, 
deleting undeletable objects, generating REXX 
scripts, managing icons, and so on. A SOM exten- 
sion to the Workplace Shell, DeskMan/2 provides 
both GUI and programmatic interfaces, is CID 
enabled, and allows adminstrators to restrict 
access to individual DeskMan/2 features on a 
user-by-user basis. 


Development Technologies Inc. 
Phone: (803) 790-9230 


Distributed Application/2. IBM's Distributed Appli- 
cation/2 (DA/2) is a set of APIs that provide a 
consistent way to access interprocess and network 
communication functions under OS/2 2.0, making 
client/server applications easy to create. The APIs 
hide the complexity of the supported communica- 
tions protocols (APPC, NetBIOS, and OS/2 named 
pipes) and enable protocol selection at run time 
without requiring cede changes. 


IBM Corp. 
Phone: (800) 342-6672 


HALO Imaging Library. Media Cybernetics’ HALO 
Imaging Library (HIL) offers developers the ability 
to add color, grayscale, and binary images to 32-bit 
applications quickly and easily. HIL provides 
more than 100 imaging functions and commands, 
enabling programmers to develop C programs 
that can read and store image files in several file 
formats and perform sophisticated processing of 
images in memory. A single HIL OS/2 worksta- 
tion license costs $599.00. 


Media Cybernetics Inc. 
Phone: (301) 495-3305 Fax: (301) 495-5964 


KiShell. A workflow process modeling and enact- 
ment tool that takes advantage of modeling tech- 
niques like IDEF, UES Computing Environments’ 
KIShell is the first commercial process manage- 
ment tool that can declaritively model work activ- 
ities and synchrionization, user responsibilities, 
and information, and tool use in a reengineered 
business process. KI Shell also enhances software 
engineering environments by integrating method- 
ology process support, software project and struc- 
ture information, and multi-vendor CASE tools. 


UES Corp. 
Phone: (614) 792-9993 Fax: (614) 792-0998 


XPRO 5.0. A Prolog system for building intelligent 
applications that run in the 32-bit OS/2 enviren- 
ment, Rational Visions’ XPRO 5.0 is designed to 
work with developers’ C or C++ code. Consisting 
of the XPRO Developer, the XPRO Engine, and the; 
XPRO Rule Compiler, the system will cost $399 
until December 31, 1993; after that $499. 


Rational Visions 
Phone: (602) 846-0371 
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C-Kermit. Columbia University’s C-Ker- 
—S\_J mit is a full-function communications 
software package for OS/2. With a built-in VT102 
terminal emulator with screen, screen rollback, and 
color and printer control, C-Kermit allows easy 
switching among applications. Distribution fees 
range from $45.00 to $220.00; call for a catalogue. 


Kermit Distribution, Columbia University 
Phone (212) 854-3703 Fax (212) 662-6442 


FAR Fax. A multi-application fax platform from Far 
Systems, FAR Fax is a stand-alone fax server for 
automating functions such as fax broadcasting or 
retrieval. FAR Fax supports Brooktrout fax boards. 


Far Systems Inc. 


Phone: (414) 563-2221 Fax: (414) 563-1865 

















IBM ARTIC960. IBM's first 32-bit communications 
coprocessor adapter card for Micro Channel-com- 
patible systems such as the IBM PS/2 enables 
computers to communicate much more quickly. 
ARTIC offloads compute-intensive tasks, resulting 
in increased communications capabilities and 
improved performance. Cards start at $2,200. 


IBM Corp. Phone: (800) 342-6672 


IBM X Window System Client Kit and OS/Windows 
Access. These two new products from IBM let users 
run X Window System applications and DOS or 
Windows TCP/IP applications, respectively, on 
OS/2. The X Window kit also lets applications run 
from OS/2 or another X Window server, while 
OS/Windows Access can also run applications 
written for DOS 2.1 in an OS/2 DOS session. 


IBM Corp. Phone: (800) 342-6672 





DEVELOPER SUPPORT 


0S/2 Screen Saver Contest. BocaSoft, The 
IBM Developer Connection CD, and 
OS/2 Developer announce the 1993 OS/2 Screen 
Saver Developer Contest. Create an OS/2 screen 
saver module and win a $1000 grand prize, OS/2 
software products, T-shirts, and more. Entries will 
= accepted in three categories: 
¢ Programmer—Submit working code for a 
screen saver module using the BocaSoft Wipe- 
Out Developer kit. 
¢ Graphic Artist—Submit a screen saver story- 
board with computer artwork included. 
¢ Video Artist—Submit a video to be converted 
into an Ultimotion movie as a screen saver 
module. 
Entries will be judged on appearance, originality, 
and functionality. BocaSoft will award prizes to the 
top three entries in each category. The grand prize 
and category winners will be selected by a panel of 
industry experts and announced at the Software 
Development Conference in March 1994. Contest 
results will be published in a future issue of OS/2 
Developer. 
Details and an official entry form are available 
on CompuServe in the BocaSoft section of the IBM 
OS/2 Vendor Forum in CONTEST.TXT. For addi- 





tional information, contact BocaSoft at 71333,3617. 
Mail entries with entry forms to: 
1993 OS/2 Screen Saver Contest 
117 NW 43rd St. 
Boca Raton, Fla. 33431 
Entries must be received before February 28, 1994. 


IBM AskPSP Expert Systems CD-ROM. IBM Personal 
Software Products’ AskPSP is an expert systems 
application that uses intelligent retrieval technolo- 
gy to provide OS/2 developers with answers to 
technical questions and problems. AskPSP, avail- 
able free as part of a pilot program, provides an 
on-line “help desk” that responds to natural lan- 
guage description of problems with answers 
culled from a library of case histories or additional 
questions that refine the search. 

For a free copy of Ask PSP, call IBM PSP Devel- 
oper Assistance at (407) 982-6408. 
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Software Installer for OS/2 lets you create C/D-enabled LAN installations, shrink-wrapped disk or CD-ROM 
installations, or installations fram a mainframe. BY KEN GREENLEE, RUSSELL SAGRAVES, RUTH WILLENBORG, 
and BRIAN YOUNG 


software Installer: 
Installations Made Easy 





( I-r) Russell Sagraves, Brian Young, 
Ruth Willenborg, Ken Greenlee 





ou've written your application and now 
you need an installation program. At a 
minimum, your customer is expecting an 
easy-to-use program that provides features such 
as allowing a choice of where to 
install your product, checking for 
the required hard disk space, and 
updating the user environment. In 
addition, many customers now 
expect a choice of disk, CD-ROM, or 
LAN install. Users can also be frus- 
trated if an install program does not 
provide an automated deletion to 
undo installation. In the LAN envi- 
ronment, customers may even want 
to install your application unattended from a cen- 
tralized location. 

Providing this level and variety of installation 
function is expensive and time-consuming. You 
would rather spend your time improving your 
application’s function, but because an installation 
program is a user's first impression of your prod- 
uct, meeting user expectations is critical. 
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SOFTWARE INSTALLER FOR OS/2 

Software Installer for OS/2 addresses user expec- 
tations about installation. For example, the unat- 
tended LAN install is supported through compli- 
ance with IBM’s Configuration, Installation, and 
Distribution (CID) architecture. The CID architec- 
ture requires each application to support the fol- 
lowing requirements: 

¢ Transfer of product to a repository 


Support of response files 

Support of command line parameters 
Generation of error and history logs 

Support for return codes to a Software Distrib- 
ution Manager (SDM). 
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CREATING YOUR INSTALLATION PROGRAM 
Once you've decided to use Software Installer, you 
need to enable your product. Users won't know 
that you are using Software Installer because your 
customized installation becomes embedded within 
the finished product. You can also provide the 
Software Installer to customers; they can use it 
later to restore, delete, and apply fixes to your 
application. 

Before beginning the enablement process, you 
need to make decisions about how your product 
will be packaged and how you want to configure 
your customer's environment: 

1. On which media (CD-ROM, disk, LAN, or host) 
will my product be delivered? 

2. Will my product be packaged as one product or 
separate products? 

3. Does my product have components? (A com- 
ponent is a portion of the product that the cus- 
tomer can optionally install.) 

4, How many directories does my product 
require? 

5. Does my product require changes to the cus- 
tomer’s CONFIG.SYS or OS2.INI? 

6. What Workplace Shell objects (such as folders 
or programs) does my product need? 

As an exercise, we will take you through the steps 
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we went through when we enabled Software 

Installer to itself. We asked ourselves the same set 

of questions and arrived at the following answers: 

1. Disk media 

2. One product 

3. Consists of four components (base install pro- 
gram, online reference, sample enablement 
files, and disk generation utility) 

4. One directory 

5. No CONFIG.SYS/OS2.INI changes 

6. One main folder on the desktop containing pro- 
gram objects for the install program and related 
utilities, the on-line reference, samples, and the 
disk generator. 

Now we are ready to begin the enablement 

process. 


ENABLEMENT STEPS 

rae ia to Software Installer takes six basic steps: 
1. Rename Software Installer product files 

2. Customize the initial screen 

3. Build a customized copy of Software 

Installer 
4. Create catalogue, package, and description 

files 
5. Create your product files 
6. Package your product. 

A full description of these steps can be found in 
the online reference provided with Software 
Installer. 

For our exercise, the enablement steps are 
shown in Figure 1. Let's look at each of them. 


RENAME SOFTWARE INSTALLER 

PRODUCT FILES 

Most Software Installer product files are shipped 
with a prefix of EPF; before you ship Software 
Installer with your product you must rename the 
files. Using the ISREN.CMD rename utility 
shipped with Software Installer, supply your own 
three character prefix and a directory for the 
renamed files. 


CUST OMIZE THE INITIAL SCREEN 

This step is probably the most fun. You get to cre- 
ate bitmaps that are used on the initial Software 
Installer screen. You can use special effects to 
move the bitmaps on the screen and make them 
appear in slices or dissolves. 





All screen customizations are done in a file 
called IIRC.RC. You will want to use the supplied 
IIRC.RC file as a starting point. 

The customized screen used by Software 
Installer is shown in Figure 2. 


Your Product 
using 
Software Installer 





Figure 1. Steps for enabling to Software Installer 


BUILD A CUSTOMIZED COPY 

OF SOFTWARE INSTALLER 

This step builds your customized copy of Software 
Installer to ship with your product. You invoke the 
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supplied BLDINST.CMD utility to cre- 
ate a packed INSTALL.IN_ file containing 
all of the customized files. 

The important thing to remember is 
that before you invoke the 
BLDINST.CMD build utility, you need 
to be in the directory in which your 
renamed copy of Software Installer was 
created. 


CREATE CATALOGUE, PACKAGE, 
AND DESCRIPTION FILES 
This step will be the most time-con- 
suming; you'll need to familiarize your- 
self with the terminology and syntax of 
the catalogue and package files. The 
terminology used in catalogue and 
package files is entry type and keyword. 
The syntax of an entry type is: 


entry type 
keywordi=valuel, 
keyword2=value2, 

. . keywordn=valuen 


Use entry types to select Software 
Installer features and keywords to 
define how the feature works. 


Catalogue File. A catalogue file is a text 
file containing information about your 
product; this information is used by 
Software Installer to install your prod- 
uct. General product information such 
as name and version/ release /modifi- 
cation number (VRM) must be provid- 
ed for all products. 

The answers you gave to the enable- 
ment questions will help you decide 
which additional entry types and key- 
words to use. 

The answers we provided to the 
enablement questions and the corre- 
sponding catalogue file entries to use 
are shown below: 

1. Disk—use the DRIVE: value keyword 

2. One product—use one PACKAGE entry 
type. 

As an example, a subset of the actual 

catalogue file is shown in Figure 5. For 

a complete list of catalogue file entry 

types, see Table 1. 


Package File. A package file is a text file 
that contains information about your 


Installation 
Fe 


= lal 


21” 








Figure 2. Software Installer's customized screen 


Install - directories 


Select the components that you want to install: 


\Installation program 
MOTniilntemeleletliiccineclicele 
| Sample files 
Ni) DISKGEN 


ki 
Bytes needed: 





ji _ Descriptions... | 


“4 Deselect all 





Ey 
2,850,000 


| Enter the directories where you want to install the components. 


These directories will be created if they do not already exist. 





Installation directory 





product files; this information is used 
by Software Installer to install your 
product and to customize your cus- 
tomer’s workstation. General product 
information such as service level must 
be provided. 

The answers you gave to the enable- 
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Figure 3. Software Installer's Install-directories dialogue 


ment questions will help you decide 
which additional entry types and key- 
words to use. 

The answers we provided to the 
enablement question and the corre- 
sponding package file entries to use are 
shown here: 


OS/2 DEVELOPER 


1. Disk—use the DRIVE: value on the 
SOURCE keyword of the FILE. 
Entry type—use a DISK entry for 
the one disk we ship. 

3. Yes—use four COMPONENT 
entries, one for each component. 

4. One directory—our PATH entry 
contains only the FILE keyword. 

6. One main folder—use the CRE- 
ATEWPSOBJECT and DELETEWP- 
SOBJECT exits. 

For example, a subset of our Software 

Installer package file is shown in Fig- 

ure 6. For a complete list of Software 

Installer exits, see Table 2. For a com- 

plete list of package file entry types, see 

Table 3. 


Description File. A description file is a 
text file that contains a brief description 
of the product. The text in the descrip- 
tion file is displayed exactly as you 
type it. The only formatting that occurs 
is word wrapping. 

For a simple disk installation, you 
do not need a description file. 


COLLECT YOUR PRODUCT FILES 

In this step, you should move all your 
product files to a central location for 
packaging. 


PACKAGE YOUR PRODUCT 

In this step you create a master copy of 
your product that will be shipped to 
customers. If you are shipping your 
product on disk, a disk generator utility 
is provided to place your files onto the 
disks. 

If you decide to make your product 
available on both disk and CD-ROM, 
you will need two package files: one for 
the disk installation and one for the 
CD-ROM installation. 


INSTALLING YOUR PRODUCT 

To start an installation from a disk, 
insert the disk into the A: drive and 
enter A:\INSTALL. Your installation will 
display your customized screen, 
prompt the user whether to update his 
or her CONFIG.SYS, prompt the user 
to select the components, display a 
progress indicator as the component 
files are installed, and display a mes- 


sage when the installation is complete. 

See Figure 3 for a picture of Soft- 
ware Installer’s Directories dialogue. 
See Figure 4 for a picture of the 
Progress dialogue. 





LAN AND HOST SUPPORT 

For the LAN environment, both reposi- 
tory and server/requester scenarios are 
supported. The repository scenario 
allows the application to be installed on 
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a LAN server that is the source of the 
install for all workstations that have 
access to the server. In this scenario, the 
entire application would be transferred 
to each requester that initiates an install. 

The server/requester scenario 
allows a part of the application to be 
installed on a server and then shared 
by all requesters. This part only exists 
on the LAN server and is never 
installed onto the requesters. A sepa- 
rate part of the application that can’t be 
shared is installed on each requester. 
Depending upon how the application 
uses Software Installer, this piece can 
be installed on each requester from the 
server or from one of the other media, 
such as a CD-ROM. 

For the host environment, Software 
Installer supports installation from a 
system running one of the following 
operating systems: 

* Multiple Virtual Storage (MVS) 

¢ Virtual Machine (VM) 

¢ Operating System/400 (OS/400) 
with IBM PC Support/400 

¢ Virtual Storage Extended (VSE/ 
ESA) 1.3.0. 


ADVANCED TOPICS 


Maintenance Functions. Software Installer 
includes maintenance functions for 
updating, restoring, and deleting. You 
do not need to make any special modi- 
fications to your catalogue or package 
file to access these functions; they may 
be accessed through either a command 
line parameter or a Software Installer 
dialogue. 


User Exits. You may be thinking that 
your product installation is too specific 
to be handled by a generic installation 
package. Perhaps you bring up dia- 
logues at various points of your current 
installation to prompt for information 
about the user’s system or the user’s 
choice of configuration options. Then 
you use this input to finish installation 
and configuration of the product. 
Software Installer is capable of han- 
dling even the most unique installation 
processes. This is done by allowing you 
to execute your own exits during instal- 


Install - progress 








Figure 5. Subset of Software Installer's catalogue file 


lation. You can code short exits to per- 
form tasks, such as updating configu- 
ration files used by your product, or 
bring up dialogues to prompt for addi- 
tional information. For example, you 
could code an exit to bring up a dia- 
logue to prompt for the type of printer 
the user has. 


Inter-Exit Communication. Now that your 
user exit has obtained the customer 
information you needed to continue 
with the install, how do you reference 
this information? 

Exits can communicate back to Soft- 
ware Installer and, as a result, to later 
exits during product installation. Soft- 
ware Installer provides APIs that 
enable your exits to store and retrieve 


values for variables you wish to set. By 
referencing the values of these vari- 
ables in the package file, you can deter- 
mine whether a file is to be transferred, 
a configuration file updated, or any 
other action taken. For example, you 
may wish to transfer a certain printer 
driver only if the user selected the 
printer in a previous user exit’s dia- 
logue. By setting a variable to the name 
of the printer selected, you can refer- 
ence the variable later in a FILE entry 
type to determine whether the file 
should be transferred. 


CONFIG.SYS Manipulation. Software 
Installer allows advanced manipulation 
of the CONFIG.SYS file. Using the ADD- 
CONFIG and UPDATECONFIG entry types, you 
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Figure 6. Subset of Software Installer's package file (continued on page 111) 
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¢ Tired of slow debuggers? 


¢ Can’t duplicate a reported 
customer problem? 


¢ Need to verify all. paths of 
execution without using printf? 


¢ Trying to support code in 
Dime Box, Texas, from 
Brooklyn, New York? 


Footprints is the product for you! 


Dynamic debugging 
Online monitoring/Offline analysis 
Realtime systems 
Telecommunications 
Multi-thread / multi-process 
Remote support and postmortems 


Dynamically select which 
portions of code to trace - in 
a live user environment! 


Footprints is simple to use! Just include a 
header. Link to a DLL. You're ready to call 
Footprints and begin capturing any or all 
the data you require. Footprints doesn’t 
bog down your code with constant tracing or 
file VO. The tracing only gets activated 
when and where you want it. From our 
friendly PM interface, you dynamically 
turn on one or more of up to 64 separate trace 
ids that control what data you are tracing. 
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memory as it whizzes by, or view it at your 
leisure from a file days after the fact. 


ONLY $ 99 
Call 713-871-1448 now! 


VISA/MC or send a check to 
Hardy Software Systems, Inc. 
4801 Woodway, #415 « Houston, TX 77056 
s/h charge $ 5.95 
Total Cost $104.95 
Texas residents add 8.25% sales tax. 





Hardy Software Systems, Inc. 


The Impact 
a completely new window class which allows 
the developer to specify a format string 





Company, Fax Number Page 
Borland International............ COV4 
(408) 439-0115 
Burton Systems Software............ 69 
(919) 233-0716 
TE. hae sePaiin iad sete dn nis ha alle eee 63 
(612) 339-5965 
Creative Systems Programming. ....... 3] 
(609) 234-1920 
SAE IG. is Same dae ws bs aews 43 
(310)645-1306 
Essex Systems Inc... 266 ea 
(508) 750-4699 
Gamma Tech........ ea 107 
(405) 359-7391 
COATES 2) sce Dem. wm itl ype decent eee 89 
(703) 273-3866 
Gp Systems Ine... 4 sas easlea ne oie 
(203) 873-2171 
Graphical Software Interfaces. ........ 25 
(404) 382-6374 
Hardy Software System... . 0... 04. 109 
(713) 871-1449 
PC VA a, ante, bee Sutin ott Que feces 53 
(919) 380-0757 
IBM Canada... ae eee we ee ew ne 65 
(800) 445-2426 
TBMIGIK cde ck caciace smeduwes 35 


0)11-43-1-21145-4490) 


ADVERTISER INDEX 


Company, Fax Number 


IBM Personal Software Products. .... . 10-11 
(407) 982-6408 


IBM Personal Software Products13, 15, 17, 19, 21 
(407) 982-6408 


IBM Personal Software Products ...... . 87 
(407) 982-6408 
IBM Santa Theresa Laboratories. ....... 49 
RT ao. ag aos ng a guint an gin oss be of SATE GL Labe avi 
Errisatt SOW ATE: Giga beg egret a gaat a 63 
(818) 879-5593 
Indelible Blue Inc,.......24205e4548 63 
(212) 629-8819 
MbPPSOI «4.3 6 areked Pare Dak iw « eee 45 
(503) 645-4576 
et a nn ee ere. 7, 
(404) 448-4163 
Levine Computer Consultants......... 25 
(703) 790-1660 
Micro Focus. .... rsa ee ae 2 
(415) 856-6134 
MirrohormaliC: coocacuuaazilseaaaa 73 
(203) 648-9587 
Mitnor Software. ......5..+e0ee8: 79 
(918) 357-2869 
og, ene eee ee ore ae 27 
Op-Tech Data Processing. ........... 63 


(702) 588-7576 














ie id Oe PE 


Formatted En 


tryfields are 
custom fields like; 





The developer has complete control to create 


* Numeric entry only 








Page 


Company, Fax Number 


Page 
Parallel Storage Solutions ........... 25 
(914) 347-4646 
Programmer's Paradise ............. 4 
Ca occ bss dias Ra a ee ee 
(805) 966-6424 
Real Time Technologies .......-..-, 63 
(708) 446-6886 
RA MOteN FG: ee ing cy.g. al atari arses spe Aad B5 
(408) 370-1171 
Rimetar Technology.) 4.6 Spc hee 
(603) 778-2408 
Sequiter Software... ....5664464 COV3 
(403) 448-0315 
STORE a so acie 0 slp 7g ke eels 95 
(617) 864-7747 
Technically Speaking. ........ bn aot 63 
(508) 681-7320 
Token Technology. ...............33 
(415) 965-8658 
Van Nostrand Reinhold ............55 
(606) 525-7778 
Walnut Creek CDROM. ..........6.. 63 
(510) 674-0821 
Watcom C forIBMPCs .......... COVI 
(519) 74/-4971 
AMC Sotware ING: ¢.65.65 iver wraeans 29 
(801) 785-8996 


Invest a stamp 





Save a bundle 


For the price of a stamp, you can get the latest edition of the federal government's free 
Consumer Information Catalog listing more than 200 free or low-cost government 


publications on topics such as federal benefits, jobs, health, housing, education, cars, 


when the entryfield is created. fyweire, © Alpha characters only 
con be used for fields like Phone Number, eae ses | 
Dates, Social Security Number, etc. Special delimiting characters 
| * Value ranges | 
The Impact Formatted Entryfield * Currency support 
| dynamically formats itself as the and, much more. 
| user inputs data. Easy to use! Just change the window class in 
| your resource file. 
| The Impact Formatted Entrytield Download free demo at 
support assures sear ica Entryfields from our BBS. 
data entry. (818) 879-7405 





IMPACT SOFTWARE 


5889 Konon Rd. 
Swite 330 
Agoura Hills 
CA 91301 


Add Impact to your application | 


To order coll or write 
(B00) 676-9390 
(818) 879 5592 
FAM (818) 879-5593 


and much more. Our booklets will help you save money, make money, 


and spend it a lithe more wisely. 


So stamp out ignorance, and write today for the labest free Catalog. 


Send your name and address to: 


Consumer Information Center 


Department SB 
Pueblo, Colorado 81009 


A public service of this publication and the Commmer Information Center af the U.S. General Services Administration. 


Figure 6. Subset of Software Installer's package file (continued from page 109) 


Table 1. Catalogue file entry types 


NOVEMBER/DECEMBER 


ra33 


may add a new line or update an 
already existing line. You may position 
your new item before or after another 
item that you specify. You may also 
replace the first, last, or all occurrences 
of a line with a new line. You can 
ensure that a new line is added only if 
it does not exist already. Finally, should 
the user delete your product, the CON- 
FIG.SYS updates can be undone. 


User-Supplied Pack Utility. Files can be 
packed with either the supplied pack 
utility or a utility of your choice. You 
need only supply in the package file or 
Disk Generation Utility the name of the 
utility you wish to use in place of the 
default. 


CONCLUSION 

Software Installer for OS/2 provides a 
rich, functional installation and main- 
tenance program for applications. 
Your customers will get a great first 
impression of your product, and you 
can spend your time enhancing your 
product. 
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here is a good reason why 
your database language was 
developed in C. In fact, there 
are many good reasons. 


C code is small. C code is fast. C code 1s 
portable. C code is flexible. C is the 
language of choice for today's professional 
developer, With the growing complexity of 
database applications, C is a realistic 
alternative. Now with CodeBase 5.0, you 
can have all the functionality, simplicity and 
power of traditional database languages 
together with the benefits of C/C++. 


C speed - fast code, true executables... 


FoxPro, Clipper, and dBASE were written 
in C primarily for speed. But those compilers 
don't really compile, they combine imbedded 
language interpreters into your .EXE. Now 
that's slow. For dazzling performance you 
need the true executables of C. With 
CodeBase you get the real thing, C code. 
Consider the following statistics, from the 
publisher of Clipper: 





u- FoxPro 
= Clipper 5 


“Sieve of Erastothenes" _ 
Benchmark for Prime Number Generation 
Shows C to be incredibly faster ! 


C size - small executables, 
no added overhead... 
FoxPro, Clipper and dBASE would like you 
to believe you need their entire development 
system to build database applications. But 
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remember, those products are all written in 
C. So why do you need to lug all their extra 
code around? You don't. CodeBase is a 
complete DBMS, in C. No fat executables 
stuffed with unused code. No runtime 
modules. No royalties. Just quality C code. 
CodeBase is just what you need. 


C portability - ANSI C/C++ 

on every hardware platform... 

No other language exists on more platforms 
than C/C++. Why rewrite your entire 
application for DOS, Windows, Windows 
NT, OS/2 or UNIX? With CodeBase the 
complete C source code 1s included, so you 
can port to any platform with an ANSI C or 
C++ compiler. Now and in the future. 


dBASE Compatible data, index 
and memo files... 

You want the industry standard. You need 
compatibility. Sure, dBASE is the standard, 
but every dBASE compatible DBMS 
product uses its own unique index and memo 
file formats. Only CodeBase has them all: 
FoxPro (.cdx), Clipper (.ntx), dBASE IV 
(.mdx) and dBASE III (.ndx). Now it’s your 
choice, were compatible with you. 


Announcin 
CodeBase 5. 


The power of a complete DBMS, the benefits of C 


NEW - Multi-user sharing with 
FoxPro, Clipper and dBASE... 
Now your multi-user C/C++ programs can 
share data, index and memo files at the 
same time as concurrently running FoxPro, 
Clipper and dBASE programs. No 
incompatibilities. No waiting. 


NEW - Queries & Relations 
1000 times faster... 
CodeBase 5.0 now lets you query related 
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data files with any logical dBASE expression. 
Our new Bit Optimization Technology 
(similar to FoxPro's Rushmore technology) 
uses index files to return a query ona 1/2 
million recerd data file in just a second. 
Automatically take advantage of this query 
performance by using our new CodeReporter: 
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To use CodeReporter, —-——— 
simply draw your report, then include it in any 
program you write. Call 403/437-2410 now for 
your FREE working model of CodeReporter. 


New - Design complex reports 

in just minutes... 

Our new CodeReporter takes the painstaking 
work out of reports. Now simply design and 
draw reports interactively under Windows 3.1, 
then print or display them from any DOS, 
Windows or UNIX application. 


SPECIAL - FREE CodeReporter 
Order CodeBase 5 before June 30, 1993 
and receive CodeReporter for free! This 
offer includes our no-risk, 90-day money 
back guarantee, so order today! 
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Demand for break- 

through, 32-bit 

OS/2° applications 

is developing into a 

huge opportunity. 

That's why we developed Borland” C++ for OS/2° >the 


easiest-to-use C++ development system for world-class 


OS/2 applications. 

Borland C++ for OS/2 is eC % 
a complete application devel- Cl 
opment system. It combines , 


an industry standard-setting Borland C++ compiler and 













5] Borland C++ 
for OS/2 has 
everything 


you need to 


tools with the industrial-strength power of OS/2, 

0 building C and C++ OS/2 applic ations is faster 
and easier than ever before. Borland’s highly integrated | || 
graphical environment and visual tools raise pro- | 
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optimizations. today—and see what develops. ‘To order or to find out 
To help speed your development along, Borland more about OS/2 2.1 or Borland C++ for OS/2, call 
C++ gives you access to the largest resources of 1 800 3-IBM-OS82. In Canada. call 1 800 465-7999, 


OS/2 libraries, controls and other add-ins. So if youre hi | i” 
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